Hello, {{name}}! Your current balance is {{balance}}
+ + """ + mail = Mail() + mail.from_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(apikey='SG.your-api-key') + sg.client.mail.send.post(request_body=mail.get()) diff --git a/sendgrid/helpers/mail/personalization.py b/sendgrid/helpers/mail/personalization.py index 8bb4bed0b..8032af958 100644 --- a/sendgrid/helpers/mail/personalization.py +++ b/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): @@ -198,4 +203,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 diff --git a/test/test_mail.py b/test/test_mail.py index 7721b5205..08d0feb8e 100644 --- a/test/test_mail.py +++ b/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", "
some text here")) 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) diff --git a/use_cases/transational_templates.md b/use_cases/transational_templates.md index d3e3a005d..2d74f92a5 100644 --- a/use_cases/transational_templates.md +++ b/use_cases/transational_templates.md @@ -66,6 +66,38 @@ print(response.body) print(response.headers) ``` +### With dynamic templates + +Sendgrid dynamic templates let you leverage power of [handlebars](https://handlebarsjs.com/) +syntax to easily manage complex dynamic content in transactional emails. + +To check this example snippet, create +[transactional email template](https://sendgrid.com/dynamic_templates) with code like +```html +Hello, {{name}}! Your current balance is {{balance}}
+``` + +Than send email based on it, providing context for substitutions: +```python +from sendgrid import SendGridAPIClient +from sendgrid.helpers.mail import Email, Personalization + + +sg = SendGridAPIClient(apikey='SG.your-api-key') + +mail = Mail() +mail.from_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 = {'name': 'Bob', 'balance': 42} +mail.add_personalization(p) + +sg.client.mail.send.post(request_body=mail.get()) +``` + +Read more about dynamic templates in [docs](https://sendgrid.com/docs/User_Guide/Transactional_Templates/how_to_send_an_email_with_transactional_templates.html) + ## Without Mail Helper Class ```python @@ -113,4 +145,4 @@ except urllib.HTTPError as e: print(response.status_code) print(response.body) print(response.headers) -``` \ No newline at end of file +```