diff --git a/README.md b/README.md index c23105b48..493468279 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,20 @@ Please browse the rest of this README for further detail. We appreciate your continued support, thank you! +# Table of Contents + +* [Installation](#installation) +* [Quick Start](#quick_start) +* [Usage](#usage) +* [Use Cases](#use_cases) +* [Announcements](#announcements) +* [Roadmap](#roadmap) +* [How to Contribute](#contribute) +* [Troubleshooting](#troubleshooting) +* [About](#about) + + + # Installation ## Prerequisites @@ -45,6 +59,7 @@ using SendGrid.Helpers.Mail; // Include if you want to use the Mail Helper - [SendGrid.CSharp.HTTP.Client](https://github.com/sendgrid/csharp-http-client) - [Newtonsoft.Json](http://www.newtonsoft.com/json) + # Quick Start ## Hello Email @@ -191,6 +206,7 @@ namespace Example } ``` + # Usage - [SendGrid Docs](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html) @@ -199,14 +215,22 @@ namespace Example - [How-to: Migration from v2 to v3](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/how_to_migrate_from_v2_to_v3_mail_send.html) - [v3 Web API Mail Send Helper](https://github.com/sendgrid/sendgrid-csharp/tree/master/SendGrid/SendGrid/Helpers/Mail) + +# Use Cases + +[Examples of common API use cases](https://github.com/sendgrid/sendgrid-csharp/blob/master/USE_CASES.md), such as how to send an email with a transactional template. + + # Announcements All updates to this library is documented in our [CHANGELOG](https://github.com/sendgrid/sendgrid-csharp/blob/master/CHANGELOG.md) and [releases](https://github.com/sendgrid/sendgrid-csharp/releases). + # Roadmap If you are interested in the future direction of this project, please take a look at our open [issues](https://github.com/sendgrid/sendgrid-csharp/issues) and [pull requests](https://github.com/sendgrid/sendgrid-csharp/pulls). We would love to hear your feedback. + # How to Contribute We encourage contribution to our library (you might even score some nifty swag), please see our [CONTRIBUTING](https://github.com/sendgrid/sendgrid-csharp/tree/master/CONTRIBUTING.md) guide for details. @@ -218,10 +242,12 @@ Quick links: - [Sign the CLA to Create a Pull Request](https://github.com/sendgrid/sendgrid-csharp/tree/master/CONTRIBUTING.md#cla) - [Improvements to the Codebase](https://github.com/sendgrid/sendgrid-csharp/tree/master/CONTRIBUTING.md#improvements_to_the_codebase) + # Troubleshooting Please see our [troubleshooting guide](https://github.com/sendgrid/sendgrid-csharp/blob/master/TROUBLESHOOTING.md) for common library issues. + # About sendgrid-csharp is guided and supported by the SendGrid [Developer Experience Team](mailto:dx@sendgrid.com). diff --git a/SendGrid/Example/Example.cs b/SendGrid/Example/Example.cs index 75c3b47ed..72bf4ef57 100644 --- a/SendGrid/Example/Example.cs +++ b/SendGrid/Example/Example.cs @@ -15,11 +15,84 @@ private static void Main() HelloEmail().Wait(); // this will actually send an email KitchenSink().Wait(); // this will only send an email if you set SandBox Mode to false + // v3 Template Example with Mail Helper + TemplateWithHelper().Wait(); + + // v3 Template Example without Mail Helper + TemplateWithoutHelper().Wait(); + // v3 Web API ApiKeys().Wait(); } + private static async Task TemplateWithHelper() + { + String apiKey = Environment.GetEnvironmentVariable("SENDGRID_APIKEY", EnvironmentVariableTarget.User); + dynamic sg = new SendGrid.SendGridAPIClient(apiKey, "https://api.sendgrid.com"); + + Email from = new Email("dx@sendgrid.com"); + String subject = "I'm replacing the subject tag"; + Email to = new Email("elmer@sendgrid.com"); + Content content = new Content("text/html", "I'm replacing the body tag"); + Mail mail = new Mail(from, subject, to, content); + + mail.TemplateId = "13b8f94f-bcae-4ec6-b752-70d6cb59f932"; + mail.Personalization[0].AddSubstitution("-name-", "Example User"); + mail.Personalization[0].AddSubstitution("-city-", "Denver"); + + dynamic response = await sg.client.mail.send.post(requestBody: mail.Get()); + Console.WriteLine(response.StatusCode); + Console.WriteLine(response.Body.ReadAsStringAsync().Result); + Console.WriteLine(response.Headers.ToString()); + + Console.ReadLine(); + + } + + private static async Task TemplateWithoutHelper() + { + String apiKey = Environment.GetEnvironmentVariable("SENDGRID_APIKEY", EnvironmentVariableTarget.User); + dynamic sg = new SendGrid.SendGridAPIClient(apiKey, "https://api.sendgrid.com"); + + string data = @"{ + 'personalizations': [ + { + 'to': [ + { + 'email': 'elmer@sendgrid.com' + } + ], + 'substitutions': { + '-name-': 'Example User', + '-city-': 'Denver' + }, + 'subject': 'I\'m replacing the subject tag' + } + ], + 'from': { + 'email': 'dx@sendgrid.com' + }, + 'content': [ + { + 'type': 'text/html', + 'value': 'I\'m replacing the body tag' + } + ], + 'template_id': '13b8f94f-bcae-4ec6-b752-70d6cb59f932' + }"; + //test @example.com + Object json = JsonConvert.DeserializeObject(data); + dynamic response = await sg.client.mail.send.post(requestBody: json.ToString()); + + Console.WriteLine(response.StatusCode); + Console.WriteLine(response.Body.ReadAsStringAsync().Result); + Console.WriteLine(response.Headers.ToString()); + + Console.ReadLine(); + + } + private static async Task HelloEmail() { String apiKey = Environment.GetEnvironmentVariable("SENDGRID_APIKEY", EnvironmentVariableTarget.User); @@ -33,13 +106,6 @@ private static async Task HelloEmail() Email email = new Email("test2@example.com"); mail.Personalization[0].AddTo(email); - // If you want to use a transactional [template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html), - // the following code will replace the above subject and content. The sample code assumes you have defined - // substitution variables [KEY_1] and [KEY_2], to be replaced by VALUE_1 and VALUE_2 respectively, in your template. - //mail.TemplateId = "TEMPLATE_ID"; - //mail.Personalization[0].AddSubstitution("[KEY_1]", "VALUE_1"); - //mail.Personalization[0].AddSubstitution("[KEY_2]", "VALUE_2"); - dynamic response = await sg.client.mail.send.post(requestBody: mail.Get()); Console.WriteLine(response.StatusCode); Console.WriteLine(response.Body.ReadAsStringAsync().Result); diff --git a/USE_CASES.md b/USE_CASES.md new file mode 100644 index 000000000..0b6f50ce6 --- /dev/null +++ b/USE_CASES.md @@ -0,0 +1,135 @@ +This documentation provides examples for specific use cases. Please [open an issue](https://github.com/sendgrid/sendgrid-sharp/issues) or make a pull request for any use cases you would like us to document here. Thank you! + +# Table of Contents + +* [Transactional Templates](#transactional_templates) + + +# Transactional Templates + +For this example, we assume you have created a [transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). Following is the template content we used for testing. + +Template ID (replace with your own): + +```text +13b8f94f-bcae-4ec6-b752-70d6cb59f932 +``` + +Email Subject: + +```text +<%subject%> +``` + +Template Body: + +```html + + + + + +Hello -name-, +

+I'm glad you are trying out the template feature! +

+<%body%> +

+I hope you are having a great day in -city- :) +

+ + +``` + +## With Mail Helper Class + +```charp +using System; +using SendGrid; +using SendGrid.Helpers.Mail; +using System.Threading.Tasks; + +namespace Example +{ + internal class Example + { + private static void Main() + { + Execute().Wait(); + } + + static async Task Execute() + { + string apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY", EnvironmentVariableTarget.User); + dynamic sg = new SendGridAPIClient(apiKey); + + Email from = new Email("test@example.com"); + String subject = "I'm replacing the subject tag"; + Email to = new Email("test@example.com"); + Content content = new Content("text/html", "I'm replacing the body tag"); + Mail mail = new Mail(from, subject, to, content); + + mail.TemplateId = "13b8f94f-bcae-4ec6-b752-70d6cb59f932"; + mail.Personalization[0].AddSubstitution("-name-", "Example User"); + mail.Personalization[0].AddSubstitution("-city-", "Denver"); + + dynamic response = await sg.client.mail.send.post(requestBody: mail.Get()); + } + } +} +``` + +## Without Mail Helper Class + +```csharp +using System; +using SendGrid; +using Newtonsoft.Json; // You can generate your JSON string yourelf or with another library if you prefer +using System.Threading.Tasks; + +namespace Example +{ + internal class Example + { + private static void Main() + { + Execute().Wait(); + } + + static async Task Execute() + { + String apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY", EnvironmentVariableTarget.User); + dynamic sg = new SendGridAPIClient(apiKey); + + string data = @"{ + 'personalizations': [ + { + 'to': [ + { + 'email': 'test@example.com' + } + ], + 'substitutions': { + '-name-': 'Example User', + '-city-': 'Denver' + }, + 'subject': 'I\'m replacing the subject tag' + } + ], + 'from': { + 'email': 'test@example.com' + }, + 'content': [ + { + 'type': 'text/html', + 'value': 'I\'m replacing the body tag' + } + ], + 'template_id': '13b8f94f-bcae-4ec6-b752-70d6cb59f932' + }"; + Object json = JsonConvert.DeserializeObject(data); + dynamic response = await sg.client.mail.send.post(requestBody: json.ToString()); + } + } +} +``` \ No newline at end of file