"))
+mail_settings.sandbox_mode = SandBoxMode(True)
+mail_settings.spam_check = SpamCheck(
+ True,
+ SpamThreshold(5),
+ SpamUrl("https://example.com"))
+message.mail_settings = mail_settings
+
+tracking_settings = TrackingSettings()
+tracking_settings.click_tracking = ClickTracking(True, False)
+tracking_settings.open_tracking = OpenTracking(
+ True,
+ OpenTrackingSubstitutionTag("open_tracking"))
+tracking_settings.subscription_tracking = SubscriptionTracking(
+ True,
+ SubscriptionText("Goodbye"),
+ SubscriptionHtml("Goodbye!"),
+ SubscriptionSubstitutionTag("unsubscribe"))
+tracking_settings.ganalytics = Ganalytics(
+ True,
+ UtmSource("utm_source"),
+ UtmMedium("utm_medium"),
+ UtmTerm("utm_term"),
+ UtmContent("utm_content"),
+ UtmCampaign("utm_campaign"))
+message.tracking_settings = tracking_settings
+try:
+ sendgrid_client = SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
+ response = sendgrid_client.send(message)
+ print(response.status_code)
+ print(response.body)
+ print(response.headers)
+except Exception as e:
+ print(e.message)
+```
\ No newline at end of file
diff --git a/use_cases/legacy_templates.md b/use_cases/legacy_templates.md
new file mode 100644
index 000000000..0cb5877f4
--- /dev/null
+++ b/use_cases/legacy_templates.md
@@ -0,0 +1,116 @@
+# Legacy Templates
+
+For this example, we assume you have created a [legacy template](https://sendgrid.com/docs/ui//sending-email/create-and-edit-legacy-transactional-templates). 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
+
+```python
+import sendgrid
+import os
+from sendgrid.helpers.mail import Email, Content, Substitution, Mail
+try:
+ # Python 3
+ import urllib.request as urllib
+except ImportError:
+ # Python 2
+ import urllib2 as urllib
+
+sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY'))
+from_email = Email("test@example.com")
+subject = "I'm replacing the subject tag"
+to_email = Email("test@example.com")
+content = Content("text/html", "I'm replacing the body tag")
+mail = Mail(from_email, subject, to_email, content)
+mail.personalizations[0].add_substitution(Substitution("-name-", "Example User"))
+mail.personalizations[0].add_substitution(Substitution("-city-", "Denver"))
+mail.template_id = "13b8f94f-bcae-4ec6-b752-70d6cb59f932"
+try:
+ response = sg.client.mail.send.post(request_body=mail.get())
+except urllib.HTTPError as e:
+ print (e.read())
+ exit()
+print(response.status_code)
+print(response.body)
+print(response.headers)
+```
+
+## Without Mail Helper Class
+
+```python
+import sendgrid
+import os
+try:
+ # Python 3
+ import urllib.request as urllib
+except ImportError:
+ # Python 2
+ import urllib2 as urllib
+
+sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY'))
+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"
+}
+try:
+ response = sg.client.mail.send.post(request_body=data)
+except urllib.HTTPError as e:
+ print (e.read())
+ exit()
+print(response.status_code)
+print(response.body)
+print(response.headers)
+```
\ No newline at end of file
diff --git a/use_cases/send_a_single_email_to_a_single_recipient.md b/use_cases/send_a_single_email_to_a_single_recipient.md
new file mode 100644
index 000000000..48ae13b37
--- /dev/null
+++ b/use_cases/send_a_single_email_to_a_single_recipient.md
@@ -0,0 +1,19 @@
+```python
+import os
+from sendgrid import SendGridAPIClient
+from sendgrid.helpers.mail import Mail
+
+message = Mail(
+ from_email='from_email@example.com',
+ to_emails='to@example.com',
+ subject='Sending with SendGrid is Fun',
+ html_content='and easy to do anywhere, even with Python')
+try:
+ sendgrid_client = SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
+ response = sendgrid_client.send(message)
+ print(response.status_code)
+ print(response.body)
+ print(response.headers)
+except Exception as e:
+ print(e.message)
+```
\ No newline at end of file
diff --git a/use_cases/send_a_single_email_to_multiple_recipients.md b/use_cases/send_a_single_email_to_multiple_recipients.md
new file mode 100644
index 000000000..c253951fe
--- /dev/null
+++ b/use_cases/send_a_single_email_to_multiple_recipients.md
@@ -0,0 +1,24 @@
+```python
+import os
+import json
+from sendgrid import SendGridAPIClient
+from sendgrid.helpers.mail import Mail
+
+to_emails = [
+ ('test0@example.com', 'Example Name 0'),
+ ('test1@example.com', 'Example Name 1')
+]
+message = Mail(
+ from_email=('from@example.com', 'Example From Name'),
+ to_emails=to_emails,
+ subject='Sending with SendGrid is Fun',
+ html_content='and easy to do anywhere, even with Python')
+try:
+ sendgrid_client = SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
+ response = sendgrid_client.send(message)
+ print(response.status_code)
+ print(response.body)
+ print(response.headers)
+except Exception as e:
+ print(e.message)
+```
\ No newline at end of file
diff --git a/use_cases/send_multiple_emails_to_multiple_recipients.md b/use_cases/send_multiple_emails_to_multiple_recipients.md
new file mode 100644
index 000000000..7217d0a0b
--- /dev/null
+++ b/use_cases/send_multiple_emails_to_multiple_recipients.md
@@ -0,0 +1,39 @@
+```python
+import os
+import json
+from sendgrid import SendGridAPIClient
+from sendgrid.helpers.mail import Mail, To
+
+to_emails = [
+ To(email='test+to0@example.com',
+ name='Example Name 0',
+ substitutions={
+ '-name-': 'Example Name Substitution 0',
+ '-github-': 'https://example.com/test0',
+ },
+ subject='Override Global Subject'),
+ To(email='test+to1@example.com',
+ name='Example Name 1',
+ substitutions={
+ '-name-': 'Example Name Substitution 1',
+ '-github-': 'https://example.com/test1',
+ }),
+]
+global_substitutions = {'-time-': '2019-01-01 00:00:00'}
+message = Mail(
+ from_email=('test+from@example.com', 'Example From Name'),
+ to_emails=to_emails,
+ subject='Hi -name-, this is the global subject',
+ html_content='Hello -name-, your URL is ' +
+ 'here email sent at -time-',
+ global_substitutions=global_substitutions,
+ is_multiple=True)
+try:
+ sendgrid_client = SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
+ response = sendgrid_client.send(message)
+ print(response.status_code)
+ print(response.body)
+ print(response.headers)
+except Exception as e:
+ print(e.message)
+```
\ No newline at end of file
diff --git a/use_cases/sending_html_content.md b/use_cases/sending_html_content.md
new file mode 100644
index 000000000..ba38b19aa
--- /dev/null
+++ b/use_cases/sending_html_content.md
@@ -0,0 +1,57 @@
+# Sending HTML-only Content
+
+
+Currently, we require both HTML and Plain Text content for improved deliverability. In some cases, only HTML may be available. The below example shows how to obtain the Plain Text equivalent of the HTML content.
+
+## Using `beautifulsoup4`
+
+```python
+import os
+from sendgrid import SendGridAPIClient
+from sendgrid.helpers.mail import From, To, Subject, PlainTextContent, HtmlContent, Mail
+try:
+ # Python 3
+ import urllib.request as urllib
+except ImportError:
+ # Python 2
+ import urllib2 as urllib
+from bs4 import BeautifulSoup
+
+html_text = """
+
+
+
+ Some
+
+ bad
+
+ HTML
+
+
+
+
+
+"""
+
+sendgrid_client = SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
+from_email = From("from_email@exmaple.com")
+to_email = Email("to_email@example.com")
+subject = Subject("Test Subject")
+html_content = HtmlContent(html_text)
+
+soup = BeautifulSoup(html_text)
+plain_text = soup.get_text()
+plain_text_content = Content("text/plain", plain_text)
+mail.add_content(plain_content)
+
+message = Mail(from_email, to_email, subject, plain_text_content, html_content)
+
+try:
+ response = sendgrid_client.send(message=message)
+ print(response.status_code)
+ print(response.body)
+ print(response.headers)
+except urllib.HTTPError as e:
+ print(e.read())
+ exit()
+```
\ No newline at end of file
diff --git a/use_cases/slack_event_api_integration.md b/use_cases/slack_event_api_integration.md
new file mode 100644
index 000000000..828149433
--- /dev/null
+++ b/use_cases/slack_event_api_integration.md
@@ -0,0 +1,48 @@
+# Integrate with Slack Events API
+
+It's fairly straightforward to integrate SendGrid with Slack, to allow emails to be triggered by events happening on Slack.
+
+For this, we make use of the [Official Slack Events API](https://github.com/slackapi/python-slack-events-api), which can be installed using pip.
+
+To allow our application to get notifications of slack events, we first create a Slack App with Event Subscriptions as described [here](https://github.com/slackapi/python-slack-events-api#--development-workflow)
+
+Then, we set `SENDGRID_API_KEY` _(which you can create on the SendGrid dashboard)_ and `SLACK_VERIFICATION_TOKEN` _(which you can get in the App Credentials section of the Slack App)_ as environment variables.
+
+Once this is done, we can subscribe to [events on Slack](https://api.slack.com/events) and trigger emails when an event occurs. In the example below, we trigger an email to `test@example.com` whenever someone posts a message on Slack that has the word "_help_" in it.
+
+```
+from slackeventsapi import SlackEventAdapter
+from slackclient import SlackClient
+import os
+from sendgrid import SendGridAPIClient
+from sendgrid.helpers.mail import From, To, Subject, PlainTextContent, HtmlContent, Mail
+
+sendgrid_client = SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
+
+
+SLACK_VERIFICATION_TOKEN = os.environ["SLACK_VERIFICATION_TOKEN"]
+slack_events_adapter = SlackEventAdapter(SLACK_VERIFICATION_TOKEN, "/slack/events")
+
+@slack_events_adapter.on("message")
+def handle_message(event_data):
+ message = event_data["event"]
+ # If the incoming message contains "help", then send an email using SendGrid
+ if message.get("subtype") is None and "help" in message.get('text').lower():
+ message = "Someone needs your help: \n\n %s" % message["text"]
+ r = send_email(message)
+ print(r)
+
+
+def send_email(message):
+ from_email = From("slack_integration@example.com")
+ to_email = To("test@example.com")
+ subject = Subject("Psst... Someone needs help!")
+ plain_text_content = PlainTextContent(message)
+ html_content = HtmlContent('{0}message{0}'.format('',''))
+ message = Mail(from_email, to_email, subject, plain_text_content, html_content)
+ response = sendgrid_client.send(message=message)
+ return response.status_code
+
+# Start the slack event listener server on port 3000
+slack_events_adapter.start(port=3000)
+```
diff --git a/use_cases/transational_templates.md b/use_cases/transational_templates.md
index d3e3a005d..8572d7e05 100644
--- a/use_cases/transational_templates.md
+++ b/use_cases/transational_templates.md
@@ -2,16 +2,66 @@
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):
+Email Subject:
```text
-13b8f94f-bcae-4ec6-b752-70d6cb59f932
+{{ subject }}
+```
+
+Template Body:
+
+```html
+
+
+
+
+
+Hello {{ name }},
+
+I'm glad you are trying out the template feature!
+
+I hope you are having a great day in {{ city }} :)
+
+
+
```
+```python
+import os
+import json
+from sendgrid import SendGridAPIClient
+from sendgrid.helpers.mail import Mail
+
+message = Mail(
+ from_email='from_email@example.com',
+ to_emails='to@example.com',
+ html_content='and easy to do anywhere, even with Python')
+message.dynamic_template_data = {
+ 'subject': 'Testing Templates',
+ 'name': 'Some One',
+ 'city': 'Denver'
+}
+message.template_id = 'd-f43daeeaef504760851f727007e0b5d0'
+try:
+ sendgrid_client = SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
+ response = sendgrid_client.send(message)
+ print(response.status_code)
+ print(response.body)
+ print(response.headers)
+except Exception as e:
+ print(e.message)
+```
+
+## Prevent Escaping Characters
+
+Per Handlebars' documentation: If you don't want Handlebars to escape a value, use the "triple-stash", {{{
+
+> If you include the characters ', " or & in a subject line replacement be sure to use three brackets.
+
Email Subject:
```text
-<%subject%>
+{{{ subject }}}
```
Template Body:
@@ -22,95 +72,41 @@ Template Body:
-Hello -name-,
+Hello {{{ name }}},
I'm glad you are trying out the template feature!
<%body%>
-I hope you are having a great day in -city- :)
+I hope you are having a great day in {{{ city }}} :)