Merge branch '3lnc-dynamic_template_support'

Author: thinkingserious

docker-test/entrypoint.sh

@@ -13,5 +13,5 @@ fi
 
 cd sendgrid-python
 python3.6 setup.py install
-pip install pyyaml six werkzeug flask python-http-client
+pip install pyyaml six werkzeug flask python-http-client pytest
 exec $SHELL

examples/helpers/mail/mail_example.py renamed to examples/helpers/mail_example.py

@@ -1,8 +1,6 @@
-import json
-import os
-import urllib2
+from sendgrid import SendGridAPIClient
 from sendgrid.helpers.mail import *
-from sendgrid import *
+
 
 # NOTE: you will need move this file to the root
 # directory of this project to execute properly.
@@ -218,3 +216,33 @@ def send_kitchen_sink():
 
 # this will only send an email if you set SandBox Mode to False
 send_kitchen_sink()
+
+
+def transactional_template_usage():
+    # Assumes you set your environment variable:
+    # https://github.com/sendgrid/sendgrid-python/blob/master/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key
+    
+    """
+    Sample usage of dynamic (handlebars) transactional templates.
+    To make this work, you should have dynamic template created within your
+    SendGrid account. For this particular example, template may be like::
+
+        <p>Hello, {{name}}! Your current balance is {{balance}}<p>
+
+    """
+    mail = Mail()
+    mail.from_email = Email('templates@sendgrid.com')
+    mail.template_id = 'd-your-dynamic-template-uid'
+    p = Personalization()
+    p.add_to(Email('user@example.com'))
+    p.dynamic_template_data = {
+        'name': 'Bob',
+        'balance': 42
+    }
+    mail.add_personalization(p)
+
+    sg = SendGridAPIClient()
+    response = sg.client.mail.send.post(request_body=mail.get())
+    print(response.status_code)
+    print(response.headers)
+    print(response.body)

sendgrid/helpers/mail/mail.py

@@ -1,6 +1,7 @@
 """v3/mail/send response body builder"""
 from .personalization import Personalization
 from .header import Header
+from .email import Email
 
 
 class Mail(object):
@@ -147,6 +148,8 @@ def from_email(self):
 
     @from_email.setter
     def from_email(self, value):
+        if isinstance(value, str):
+            value = Email(value)
         self._from_email = value
 
     @property

sendgrid/helpers/mail/personalization.py

@@ -1,6 +1,10 @@
 class Personalization(object):
     """A Personalization defines who should receive an individual message and
     how that message should be handled.
+
+    :var dynamic_template_data: data for dynamic transactional template.
+        Should be JSON-serializeable structure. No pre-processing sill be done
+        prior to sending this via http client.
     """
 
     def __init__(self):
@@ -13,6 +17,7 @@ def __init__(self):
         self._substitutions = []
         self._custom_args = []
         self._send_at = None
+        self._dynamic_template_data = None
 
     @property
     def tos(self):
@@ -158,6 +163,18 @@ def send_at(self):
     def send_at(self, value):
         self._send_at = value
 
+    @property
+    def dynamic_template_data(self):
+        """Data for dynamic transactional template.
+
+        :rtype: JSON-serializeable structure
+        """
+        return self._dynamic_template_data
+
+    @dynamic_template_data.setter
+    def dynamic_template_data(self, json):
+        self._dynamic_template_data = json
+
     def get(self):
         """
         Get a JSON-ready representation of this Personalization.
@@ -198,4 +215,8 @@ def get(self):
 
         if self.send_at is not None:
             personalization["send_at"] = self.send_at
+
+        if self.dynamic_template_data is not None:
+            personalization['dynamic_template_data'] = self.dynamic_template_data
+
         return personalization

test/test_mail.py

@@ -80,7 +80,6 @@ def test_sendgridAPIKey(self):
         else:
             self.fail("Should have failed as SendGrid API key included")
 
-
     def test_helloEmail(self):
         self.max_diff = None
 
@@ -130,7 +129,7 @@ def test_helloEmailAdditionalContent(self):
         personalization = Personalization()
         personalization.add_to(Email("test@example.com"))
         mail.add_personalization(personalization)
-        
+
         mail.add_content(Content("text/html", "<html><body>some text here</body></html>"))
         mail.add_content(Content("text/plain", "some text here"))
 
@@ -562,3 +561,26 @@ def test_disable_tracking(self):
     def test_directly_setting_substitutions(self):
         personalization = Personalization()
         personalization.substitutions = [{'a': 0}]
+
+    def test_dynamic_template_data(self):
+        p = Personalization()
+        p.add_to(Email('test@sendgrid.com'))
+        p.dynamic_template_data = {
+            'customer': {
+                'name': 'Bob',
+                'returning': True
+                },
+            'total': 42
+            }
+
+        expected = {
+            'to': [{'email': 'test@sendgrid.com'}],
+            'dynamic_template_data': {
+                'customer': {
+                    'name': 'Bob',
+                    'returning': True
+                    },
+                'total': 42
+                }
+        }
+        self.assertDictEqual(p.get(), expected)

use_cases/transational_templates.md

@@ -1,6 +1,71 @@
-# 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.
+Sendgrid transactional templates let you leverage power of [handlebars](https://handlebarsjs.com/)
+syntax to easily manage complex dynamic content in transactional emails.
+
+For this example, we assume you have created a [transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/create_and_edit_transactional_templates.html). Following is the template content we used for testing.
+
+This example also assumes you [set your environment variable](https://github.com/sendgrid/sendgrid-python/blob/master/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key) with your SendGrid API Key.
+
+Template ID (replace with your own):
+
+```text
+d-13b8f94fbcae4ec6b75270d6cb59f932
+```
+
+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/>
+I hope you are having a great day in {{ city }} :)
+<br /><br/>
+</body>
+</html>
+```
+
+```python
+from sendgrid import SendGridAPIClient
+from sendgrid.helpers.mail import Mail, Email, Personalization
+
+
+sg = SendGridAPIClient()
+mail = Mail()
+mail.from_email = Email('templates@example.com')
+mail.template_id = 'd-your-dynamic-template-uid'
+p = Personalization()
+p.add_to(Email('user@example.com'))
+p.dynamic_template_data = {
+  'subject': 'Dynamic Templates in Python',
+  'name': 'Example User',
+  'city': 'Denver'
+}
+mail.add_personalization(p)
+
+response = sg.client.mail.send.post(request_body=mail.get())
+print(response.status_code)
+print(response.headers)
+print(response.body)
+```
+
+Read more about dynamic templates [here](https://sendgrid.com/docs/User_Guide/Transactional_Templates/how_to_send_an_email_with_transactional_templates.html).
+
+# Legacy Templates
+
+For this example, we assume you have created a [Legacy Template](https://sendgrid.com/templates). Following is the template content we used for testing.
 
 Template ID (replace with your own):