diff --git a/examples/helpers/mail/mail_example.py b/examples/helpers/mail/mail_example.py index b2de7f0a0..fb2cded6d 100644 --- a/examples/helpers/mail/mail_example.py +++ b/examples/helpers/mail/mail_example.py @@ -35,8 +35,8 @@ def build_personalization(personalization): for header in personalization['headers']: mock_personalization.add_header(header) - for substitution in personalization['substitutions']: - mock_personalization.add_substitution(substitution) + for dynamic_template_data in personalization['dynamic_template_data']: + mock_personalization.add_dynamic_template_data(dynamic_template_data) for arg in personalization['custom_args']: mock_personalization.add_custom_arg(arg) @@ -69,8 +69,8 @@ def get_mock_personalization_dict(): mock_pers['headers'] = [Header("X-Test", "test"), Header("X-Mock", "true")] - mock_pers['substitutions'] = [Substitution("%name%", "Example User"), - Substitution("%city%", "Denver")] + mock_pers['dynamic_template_data'] = [DynamicData("name", "Example User"), + DynamicData("city", "Denver")] mock_pers['custom_args'] = [CustomArg("user_id", "343"), CustomArg("type", "marketing")] diff --git a/sendgrid/helpers/mail/dynamic_template_data.py b/sendgrid/helpers/mail/dynamic_template_data.py new file mode 100644 index 000000000..2b296d0ab --- /dev/null +++ b/sendgrid/helpers/mail/dynamic_template_data.py @@ -0,0 +1,44 @@ +class DynamicData(object): + """Handlebars compatible dynamic data to be applied to the text and HTML + contents of the body of your email, as well as in the Subject and Reply-To + parameters. + """ + + def __init__(self, key=None, value=None): + """Create DynamicData with the given key and value. + + :param key: Text to be replaced with "value" param + :type key: string, optional + :param value: Value to substitute into email + :type value: string or array of objects, optional + """ + self.key = key + self.value = value + + @property + def key(self): + return self._key + + @key.setter + def key(self, value): + self._key = value + + @property + def value(self): + return self._value + + @value.setter + def value(self, value): + self._value = value + + def get(self): + """ + Get a JSON-ready representation of this DynamicData. + + :returns: This DynamicData, ready for use in a request body. + :rtype: dict + """ + dynamic_data = {} + if self.key is not None and self.value is not None: + dynamic_data[self.key] = self.value + return dynamic_data diff --git a/sendgrid/helpers/mail/personalization.py b/sendgrid/helpers/mail/personalization.py index 8bb4bed0b..07b2e051e 100644 --- a/sendgrid/helpers/mail/personalization.py +++ b/sendgrid/helpers/mail/personalization.py @@ -1,3 +1,6 @@ +import warnings + + class Personalization(object): """A Personalization defines who should receive an individual message and how that message should be handled. @@ -10,6 +13,7 @@ def __init__(self): self._bccs = [] self._subject = None self._headers = [] + self._dynamic_template_data = [] self._substitutions = [] self._custom_args = [] self._send_at = None @@ -106,6 +110,31 @@ def add_header(self, header): """ self._headers.append(header.get()) + @property + def dynamic_template_data(self): + """Dynamic Template Data to be applied within this Personalization. + :rtype: list(dict) + """ + return self._dynamic_template_data + + @dynamic_template_data.setter + def dynamic_template_data(self, value): + if len(self.substitutions) > 0: + warnings.warn( + "Dynamic template data should not be used in conjunction with " + "substitutions") + self._dynamic_template_data = value + + def add_dynamic_template_data(self, dynamic_template_data): + """Add a new Substitution to this Personalization. + :type substitution: Substitution + """ + if len(self.substitutions) > 0: + warnings.warn( + "Dynamic template data should not be used in conjunction with " + "substitutions") + self._dynamic_template_data.append(dynamic_template_data.get()) + @property def substitutions(self): """Substitutions to be applied within this Personalization. @@ -116,6 +145,10 @@ def substitutions(self): @substitutions.setter def substitutions(self, value): + if len(self.dynamic_template_data) > 0: + warnings.warn( + "Substitutions should not be used in conjunction with " + "dynamic template data") self._substitutions = value def add_substitution(self, substitution): @@ -123,6 +156,10 @@ def add_substitution(self, substitution): :type substitution: Substitution """ + if len(self.dynamic_template_data) > 0: + warnings.warn( + "Substitutions should not be used in conjunction with " + "dynamic template data") self._substitutions.append(substitution.get()) @property @@ -184,6 +221,12 @@ def get(self): headers.update(key) personalization["headers"] = headers + if self.dynamic_template_data: + dynamic_template_data = {} + for key in self.dynamic_template_data: + dynamic_template_data.update(key) + personalization["dynamic_template_data"] = dynamic_template_data + if self.substitutions: substitutions = {} for key in self.substitutions: diff --git a/use_cases/README.md b/use_cases/README.md index 188464d09..e4a61a975 100644 --- a/use_cases/README.md +++ b/use_cases/README.md @@ -14,7 +14,8 @@ This directory provides examples for specific use cases of this library. Please ### Working with Mail * [Asynchronous Mail Send](asynchronous_mail_send.md) * [Attachment](attachment.md) -* [Transactional Templates](transational_templates.md) +* [Dynamic Transactional Templates](dynamic_transational_templates.md) +* [Legacy Transactional Templates](legacy_transational_templates.md) ### Library Features * [Error Handling](error_handling.md) \ No newline at end of file diff --git a/use_cases/dynamic_transactional_templates.md b/use_cases/dynamic_transactional_templates.md new file mode 100644 index 000000000..4c8b66277 --- /dev/null +++ b/use_cases/dynamic_transactional_templates.md @@ -0,0 +1,114 @@ +# Transactional Templates + +For this example, we assume you have created a [dynamic transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/how_to_send_an_email_with_transactional_templates.html). Following is the template content we used for testing. + +Template ID (replace with your own): + +```text +d-5b08559ac97289da39defbb521bc62da +``` + +Email Subject: + +```text +{{subject}} +``` + +Template Body: + +```html + +
+