Add TOC for README, Add USE_CASES.md

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)
+
+
+<a name="installation"></a>
 # 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)
 
+<a name="quick_start"></a>
 # Quick Start
 
 ## Hello Email
@@ -191,6 +206,7 @@ namespace Example
 }
 ```
 
+<a name="usage"></a>
 # 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)
 
+<a name="use_cases">
+# 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.
+
+<a name="announcements"></a>
 # 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).
 
+<a name="roadmap"></a>
 # 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.
 
+<a name="contribute"></a>
 # 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)
 
+<a name="troubleshooting"></a>
 # Troubleshooting
 
 Please see our [troubleshooting guide](https://github.com/sendgrid/sendgrid-csharp/blob/master/TROUBLESHOOTING.md) for common library issues.
 
+<a name="about"></a>
 # About
 
 sendgrid-csharp is guided and supported by the SendGrid [Developer Experience Team](mailto:dx@sendgrid.com).

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 <strong>body tag</strong>");
+            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 <strong>body tag</strong>'
+                }
+              ],
+              'template_id': '13b8f94f-bcae-4ec6-b752-70d6cb59f932'
+            }";
+            //test @example.com
+            Object json = JsonConvert.DeserializeObject<Object>(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);

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)
+
+<a name="transactional_templates"></a>
+# 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
+<html>
+<head>
+	<title></title>
+</head>
+<body>
+Hello -name-,
+<br /><br/>
+I'm glad you are trying out the template feature!
+<br /><br/>
+<%body%>
+<br /><br/>
+I hope you are having a great day in -city- :)
+<br /><br/>
+</body>
+</html>
+```
+
+## 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 <strong>body tag</strong>");
+            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 <strong>body tag</strong>'
+                }
+              ],
+              'template_id': '13b8f94f-bcae-4ec6-b752-70d6cb59f932'
+            }";
+            Object json = JsonConvert.DeserializeObject<Object>(data);
+            dynamic response = await sg.client.mail.send.post(requestBody: json.ToString());
+        }
+    }
+}
+```