SendGrid library for Python
Project description
SendGrid-Python
===============
This library allows you to quickly and easily send emails through
SendGrid using Python.
.. image:: https://travis-ci.org/sendgrid/sendgrid-python.svg?branch=master
:target: https://travis-ci.org/sendgrid/sendgrid-python
Warning
-------
If you upgrade to version ``1.2.x``, the ``add_to`` method behaves differently. In the past this method defaulted to using the ``SMTPAPI`` header. Now you must explicitly call the ``smtpapi.add_to`` method. More on the ``SMTPAPI`` section.
Announcements
-------------
For users of our `Web API v3 endpoints`_, we have begun integrating v3 endpoints into this library. As part of this process we have implemented a test automation tool, TOX_. We are also updating and enhancing the core library code.
In no particular order, we have implemented a `few of the v3`_ endpoints already and would appreciate your feedback.
Thank you for your continued support!
API Key
-------
To use the SendGrid Web API, you will need an API Key. You can create one in your `SendGrid Dashboard`_.
Install
-------
.. code:: python
pip install sendgrid
# or
easy_install sendgrid
Example
-------
.. code:: python
import sendgrid
sg = sendgrid.SendGridClient('YOUR_SENDGRID_API_KEY')
message = sendgrid.Mail()
message.add_to('John Doe <john@email.com>')
message.set_subject('Example')
message.set_html('Body')
message.set_text('Body')
message.set_from('Doe John <doe@email.com>')
status, msg = sg.send(message)
#or
message = sendgrid.Mail(to='john@email.com', subject='Example', html='Body', text='Body', from_email='doe@email.com')
status, msg = sg.send(message)
Error handling
--------------
By default, ``.send`` method returns a tuple ``(http_status_code, message)``,
however you can pass ``raise_errors=True`` to ``SendGridClient`` constructor,
then ``.send`` method will raise ``SendGridClientError`` for 4xx errors,
and ``SendGridServerError`` for 5xx errors.
.. code:: python
from sendgrid import SendGridError, SendGridClientError, SendGridServerError
sg = sendgrid.SendGridClient('YOUR_SENDGRID_API_KEY', None, raise_errors=True)
try:
sg.send(message)
except SendGridClientError:
...
except SendGridServerError:
...
This behavior is going to be default from version 2.0.0. You are
encouraged to set ``raise_errors`` to ``True`` for forwards compatibility.
``SendGridError`` is a base-class for all SendGrid-related exceptions.
Usage
~~~~~
To begin using this library create a new instance of `SendGridClient` with your SendGrid API Key. To configure API keys, visit https://app.sendgrid.com/settings/api_keys.
.. code:: python
sg = sendgrid.SendGridClient('YOUR_SENDGRID_API_KEY')
Methods
~~~~~~~
There are multiple ways to add recipients:
add_to
^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_to('example@email.com')
# or
message.add_to('Example Dude <example@email.com>')
# or
message.add_to(['Example Dude <example@email.com>', 'john@email.com'])
add_to_name
^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_to('example@email.com')
message.add_to_name('Example Dude')
add_cc
^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_cc('example@email.com')
message.add_cc(['example@email.com', 'john@email.com'])
add_bcc
^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_bcc('example@email.com')
# or
message.add_bcc(['Example Dude <example@email.com>', 'john@email.com'])
set_from
^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_from('example@email.com')
set_from_name
^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_from('example@email.com')
message.set_from_name('Example Dude')
set_replyto
^^^^^^^^^^^
.. code:: python
message.sendgrid.Mail()
message.set_replyto('example@email.com')
set_subject
^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_subject('Example')
set_text
^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_text('Body')
set_html
^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_html('<html><body>Stuff, you know?</body></html>')
set_date
^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_date('Wed, 17 Dec 2014 19:21:16 +0000')
set_headers
^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_headers({'X-Sent-Using': 'SendGrid-API', 'X-Transport': 'web'});
Set File Attachments
~~~~~~~~~~~~~~~~~~~~
There are multiple ways to work with attachments:
add_attachment
^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_attachment('stuff.txt', './stuff.txt')
# or
message.add_attachment('stuff.txt', open('./stuff.txt', 'rb'))
add_attachment_stream
^^^^^^^^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_attachment_stream('filename', 'somerandomcontentyouwant')
# strings, unicode, or BytesIO streams
add_content_id
^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_attachment('image.png', open('./image.png', 'rb'))
message.add_content_id('image.png', 'ID_IN_HTML')
message.set_html('<html><body>TEXT BEFORE IMAGE<img src="cid:ID_IN_HTML"></img>AFTER IMAGE</body></html>')
WEB API v3
----------
To use the SendGrid Web API v3, you will need an API Key. You can create one in your `SendGrid Dashboard`_.
.. _APIKeysAnchor:
`APIKeys`_
~~~~~~~~~~
List all API Keys belonging to the authenticated user.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
status, msg = client.apikeys.get()
Generate a new API Key for the authenticated user
.. code:: python
client = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
name = "My Amazing API Key"
status, msg = client.apikeys.post(name)
Revoke an existing API Key
.. code:: python
client = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
status, msg = client.apikeys.delete(api_key_id)
Update the name of an existing API Key
.. code:: python
client = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
name = "My NEW API Key 3000"
status, msg = client.apikeys.patch(api_key_id, name)
`Suppression Management`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unsubscribe Manager gives your recipients more control over the types of emails they want to receive by letting them opt out of messages from a certain type of email.
Unsubscribe Groups
~~~~~~~~~~~~~~~~~~~
Retrieve all suppression groups associated with the user.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
status, msg = client.asm_groups.get()
Get a single record.
.. code:: python
status, msg = client.asm_groups.get(record_id)
Create a new suppression group.
.. code:: python
status, msg = client.asm_groups.post(name, description, is_default)
Suppressions
~~~~~~~~~~~~~~~~
Suppressions are email addresses that can be added to groups to prevent certain types of emails from being delivered to those addresses.
Add recipient addresses to the suppressions list for a given group.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
group_id = <group_id_number> # If no group_id_number, the emails will be added to the global suppression group
emails = ['example@example.com', 'example@example.com']
status, msg = client.asm_suppressions.post(group_id, emails)
Get suppressed addresses for a given group.
.. code:: python
status, msg = client.asm_suppressions.get(<group_id>)
Delete a recipient email from the suppressions list for a group.
.. code:: python
status, msg = client.asm_suppressions.delete(<group_id>,<email_address>)
Global Suppressions
~~~~~~~~~~~~~~~~~~~~~~~
Global Suppressions are email addresses that will not receive any emails.
Check if a given email is on the global suppression list.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
email = ['example@example.com']
status, msg = client.asm_global_suppressions.get(email)
Get a list of all SendGrid globally unsubscribed emails.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
status, msg = client.suppressions.get()
Add an email to the global suppression list.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
email = ['example@example.com']
status, msg = client.asm_global_suppressions.post(email)
Delete an email from the global suppression list.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
email = 'example@example.com'
status, msg = client.asm_global_suppressions.delete(email)
`Global Stats`_
~~~~~~~~~~~~~~~~~~~~~~~
Global Stats provide all of your user's email statistics for a given date range.
.. code:: python
start_date = '2015-10-01' # required
end_date = None # optional
aggregated_by = 'week' # optional, must be day, week or month
status, msg = client.stats.get(start_date, end_date, aggregated_by)
SendGrid's `X-SMTPAPI`_
-----------------------
If you wish to use the X-SMTPAPI on your own app, you can use the
`SMTPAPI Python library`_.
There are implementations for setter methods too.
Example
~~~~~~~
.. code:: python
sg = sendgrid.SendGridClient('SENDGRID_API_KEY')
message = sendgrid.Mail()
message.add_substitution(':first_name', 'John')
message.smtpapi.add_to('John <example@example.com>')
message.set_subject('Testing from the Python library using the SMTPAPI')
message.set_html('<b>:first_name, this was a successful test of using the SMTPAPI library!</b>')
message.set_text(':name, this was a successful test of using the SMTPAPI library!')
message.set_from('Jane <example@example.com>')
sg.send(message)
`Recipients`_
~~~~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_to('example@email.com')
`Substitution`_
~~~~~~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_substitution('key', 'value')
add_substitution
^^^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_substitution('key', 'value')
set_substitutions
^^^^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_substitutions({'key1': ['value1', 'value2'], 'key2': ['value3', 'value4']})
`Section`_
~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_section('section', 'value')
add_section
^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_section('section', 'value')
set_sections
^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_sections({'section1': 'value1', 'section2': 'value2'})
`Category`_
~~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_category('category')
add_category
^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_category('category')
set_categories
^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_categories(['category1', 'category2'])
`Unique Arguments`_
~~~~~~~~~~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_unique_arg('key', 'value')
add_unique_arg
^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_unique_arg('key', 'value')
set_unique_args
^^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_unique_args({'key1': 'value1', 'key2': 'value2'})
`Filter`_
~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_filter('filter', 'setting', 'value')
add_filter
^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_filter('filter', 'setting', 'value')
`ASM Group`_
~~~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.set_asm_group_id(value)
set_asm_group_id
^^^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_asm_group_id(value)
Using Templates from the Template Engine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code:: python
message.add_filter('templates', 'enable', '1')
message.add_filter('templates', 'template_id', 'TEMPLATE-ALPHA-NUMERIC-ID')
message.add_substitution('key', 'value')
Tests
~~~~~
**Prerequisites:**
- Mac OS X Prerequisite:
.. code:: python
xcode-select --install
- Install pyenv and tox
.. code:: python
brew update
brew install pyenv
pip install tox
- Add `eval "$(pyenv init -)"` to your profile after installing tox, you only need to do this once.
.. code:: python
pyenv install 2.6.9
pyenv install 2.7.8
pyenv install 3.2.6
pyenv install 3.3.6
pyenv install 3.4.3
pyenv install 3.5.0
**Run the tests:**
.. code:: python
virtualenv venv
source venv/bin/activate #or . ./activate.sh
python setup.py install
pyenv local 3.5.0 3.4.3 3.3.6 3.2.6 2.7.8 2.6.9
pyenv rehash
tox
Deploying
~~~~~~~~~
- Confirm tests pass
- Bump the version in `sendgrid/version.py`
- Update `CHANGELOG.md`
- Confirm tests pass
- Commit `Version bump vX.X.X`
- `python setup.py sdist bdist_wininst upload`
- Push changes to GitHub
- Release tag on GitHub `vX.X.X`
.. _X-SMTPAPI: http://sendgrid.com/docs/API_Reference/SMTP_API/
.. _SMTPAPI Python library: https://github.com/sendgrid/smtpapi-python
.. _Substitution: http://sendgrid.com/docs/API_Reference/SMTP_API/substitution_tags.html
.. _Section: http://sendgrid.com/docs/API_Reference/SMTP_API/section_tags.html
.. _Category: http://sendgrid.com/docs/Delivery_Metrics/categories.html
.. _Unique Arguments: http://sendgrid.com/docs/API_Reference/SMTP_API/unique_arguments.html
.. _Filter: http://sendgrid.com/docs/API_Reference/SMTP_API/apps.html
.. _`Web API v3 endpoints`: https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html
.. _TOX: https://testrun.org/tox/latest/
.. _`few of the v3`: APIKeysAnchor_
.. _`Suppression Management`: https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/index.html
.. _`Global Stats`: https://sendgrid.com/docs/API_Reference/Web_API_v3/Stats/global.html
.. _`SendGrid Dashboard`: https://app.sendgrid.com/settings/api_keys
===============
This library allows you to quickly and easily send emails through
SendGrid using Python.
.. image:: https://travis-ci.org/sendgrid/sendgrid-python.svg?branch=master
:target: https://travis-ci.org/sendgrid/sendgrid-python
Warning
-------
If you upgrade to version ``1.2.x``, the ``add_to`` method behaves differently. In the past this method defaulted to using the ``SMTPAPI`` header. Now you must explicitly call the ``smtpapi.add_to`` method. More on the ``SMTPAPI`` section.
Announcements
-------------
For users of our `Web API v3 endpoints`_, we have begun integrating v3 endpoints into this library. As part of this process we have implemented a test automation tool, TOX_. We are also updating and enhancing the core library code.
In no particular order, we have implemented a `few of the v3`_ endpoints already and would appreciate your feedback.
Thank you for your continued support!
API Key
-------
To use the SendGrid Web API, you will need an API Key. You can create one in your `SendGrid Dashboard`_.
Install
-------
.. code:: python
pip install sendgrid
# or
easy_install sendgrid
Example
-------
.. code:: python
import sendgrid
sg = sendgrid.SendGridClient('YOUR_SENDGRID_API_KEY')
message = sendgrid.Mail()
message.add_to('John Doe <john@email.com>')
message.set_subject('Example')
message.set_html('Body')
message.set_text('Body')
message.set_from('Doe John <doe@email.com>')
status, msg = sg.send(message)
#or
message = sendgrid.Mail(to='john@email.com', subject='Example', html='Body', text='Body', from_email='doe@email.com')
status, msg = sg.send(message)
Error handling
--------------
By default, ``.send`` method returns a tuple ``(http_status_code, message)``,
however you can pass ``raise_errors=True`` to ``SendGridClient`` constructor,
then ``.send`` method will raise ``SendGridClientError`` for 4xx errors,
and ``SendGridServerError`` for 5xx errors.
.. code:: python
from sendgrid import SendGridError, SendGridClientError, SendGridServerError
sg = sendgrid.SendGridClient('YOUR_SENDGRID_API_KEY', None, raise_errors=True)
try:
sg.send(message)
except SendGridClientError:
...
except SendGridServerError:
...
This behavior is going to be default from version 2.0.0. You are
encouraged to set ``raise_errors`` to ``True`` for forwards compatibility.
``SendGridError`` is a base-class for all SendGrid-related exceptions.
Usage
~~~~~
To begin using this library create a new instance of `SendGridClient` with your SendGrid API Key. To configure API keys, visit https://app.sendgrid.com/settings/api_keys.
.. code:: python
sg = sendgrid.SendGridClient('YOUR_SENDGRID_API_KEY')
Methods
~~~~~~~
There are multiple ways to add recipients:
add_to
^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_to('example@email.com')
# or
message.add_to('Example Dude <example@email.com>')
# or
message.add_to(['Example Dude <example@email.com>', 'john@email.com'])
add_to_name
^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_to('example@email.com')
message.add_to_name('Example Dude')
add_cc
^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_cc('example@email.com')
message.add_cc(['example@email.com', 'john@email.com'])
add_bcc
^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_bcc('example@email.com')
# or
message.add_bcc(['Example Dude <example@email.com>', 'john@email.com'])
set_from
^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_from('example@email.com')
set_from_name
^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_from('example@email.com')
message.set_from_name('Example Dude')
set_replyto
^^^^^^^^^^^
.. code:: python
message.sendgrid.Mail()
message.set_replyto('example@email.com')
set_subject
^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_subject('Example')
set_text
^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_text('Body')
set_html
^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_html('<html><body>Stuff, you know?</body></html>')
set_date
^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_date('Wed, 17 Dec 2014 19:21:16 +0000')
set_headers
^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_headers({'X-Sent-Using': 'SendGrid-API', 'X-Transport': 'web'});
Set File Attachments
~~~~~~~~~~~~~~~~~~~~
There are multiple ways to work with attachments:
add_attachment
^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_attachment('stuff.txt', './stuff.txt')
# or
message.add_attachment('stuff.txt', open('./stuff.txt', 'rb'))
add_attachment_stream
^^^^^^^^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_attachment_stream('filename', 'somerandomcontentyouwant')
# strings, unicode, or BytesIO streams
add_content_id
^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_attachment('image.png', open('./image.png', 'rb'))
message.add_content_id('image.png', 'ID_IN_HTML')
message.set_html('<html><body>TEXT BEFORE IMAGE<img src="cid:ID_IN_HTML"></img>AFTER IMAGE</body></html>')
WEB API v3
----------
To use the SendGrid Web API v3, you will need an API Key. You can create one in your `SendGrid Dashboard`_.
.. _APIKeysAnchor:
`APIKeys`_
~~~~~~~~~~
List all API Keys belonging to the authenticated user.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
status, msg = client.apikeys.get()
Generate a new API Key for the authenticated user
.. code:: python
client = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
name = "My Amazing API Key"
status, msg = client.apikeys.post(name)
Revoke an existing API Key
.. code:: python
client = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
status, msg = client.apikeys.delete(api_key_id)
Update the name of an existing API Key
.. code:: python
client = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
name = "My NEW API Key 3000"
status, msg = client.apikeys.patch(api_key_id, name)
`Suppression Management`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unsubscribe Manager gives your recipients more control over the types of emails they want to receive by letting them opt out of messages from a certain type of email.
Unsubscribe Groups
~~~~~~~~~~~~~~~~~~~
Retrieve all suppression groups associated with the user.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
status, msg = client.asm_groups.get()
Get a single record.
.. code:: python
status, msg = client.asm_groups.get(record_id)
Create a new suppression group.
.. code:: python
status, msg = client.asm_groups.post(name, description, is_default)
Suppressions
~~~~~~~~~~~~~~~~
Suppressions are email addresses that can be added to groups to prevent certain types of emails from being delivered to those addresses.
Add recipient addresses to the suppressions list for a given group.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
group_id = <group_id_number> # If no group_id_number, the emails will be added to the global suppression group
emails = ['example@example.com', 'example@example.com']
status, msg = client.asm_suppressions.post(group_id, emails)
Get suppressed addresses for a given group.
.. code:: python
status, msg = client.asm_suppressions.get(<group_id>)
Delete a recipient email from the suppressions list for a group.
.. code:: python
status, msg = client.asm_suppressions.delete(<group_id>,<email_address>)
Global Suppressions
~~~~~~~~~~~~~~~~~~~~~~~
Global Suppressions are email addresses that will not receive any emails.
Check if a given email is on the global suppression list.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
email = ['example@example.com']
status, msg = client.asm_global_suppressions.get(email)
Get a list of all SendGrid globally unsubscribed emails.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
status, msg = client.suppressions.get()
Add an email to the global suppression list.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
email = ['example@example.com']
status, msg = client.asm_global_suppressions.post(email)
Delete an email from the global suppression list.
.. code:: python
client = sendgrid.SendGridAPIClient('SENDGRID_API_KEY')
email = 'example@example.com'
status, msg = client.asm_global_suppressions.delete(email)
`Global Stats`_
~~~~~~~~~~~~~~~~~~~~~~~
Global Stats provide all of your user's email statistics for a given date range.
.. code:: python
start_date = '2015-10-01' # required
end_date = None # optional
aggregated_by = 'week' # optional, must be day, week or month
status, msg = client.stats.get(start_date, end_date, aggregated_by)
SendGrid's `X-SMTPAPI`_
-----------------------
If you wish to use the X-SMTPAPI on your own app, you can use the
`SMTPAPI Python library`_.
There are implementations for setter methods too.
Example
~~~~~~~
.. code:: python
sg = sendgrid.SendGridClient('SENDGRID_API_KEY')
message = sendgrid.Mail()
message.add_substitution(':first_name', 'John')
message.smtpapi.add_to('John <example@example.com>')
message.set_subject('Testing from the Python library using the SMTPAPI')
message.set_html('<b>:first_name, this was a successful test of using the SMTPAPI library!</b>')
message.set_text(':name, this was a successful test of using the SMTPAPI library!')
message.set_from('Jane <example@example.com>')
sg.send(message)
`Recipients`_
~~~~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_to('example@email.com')
`Substitution`_
~~~~~~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_substitution('key', 'value')
add_substitution
^^^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_substitution('key', 'value')
set_substitutions
^^^^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_substitutions({'key1': ['value1', 'value2'], 'key2': ['value3', 'value4']})
`Section`_
~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_section('section', 'value')
add_section
^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_section('section', 'value')
set_sections
^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_sections({'section1': 'value1', 'section2': 'value2'})
`Category`_
~~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_category('category')
add_category
^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_category('category')
set_categories
^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_categories(['category1', 'category2'])
`Unique Arguments`_
~~~~~~~~~~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_unique_arg('key', 'value')
add_unique_arg
^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_unique_arg('key', 'value')
set_unique_args
^^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_unique_args({'key1': 'value1', 'key2': 'value2'})
`Filter`_
~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.add_filter('filter', 'setting', 'value')
add_filter
^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.add_filter('filter', 'setting', 'value')
`ASM Group`_
~~~~~~~~~~~~
.. code:: python
message = sendgrid.Mail()
message.smtpapi.set_asm_group_id(value)
set_asm_group_id
^^^^^^^^^^^^^^^^
.. code:: python
message = sendgrid.Mail()
message.set_asm_group_id(value)
Using Templates from the Template Engine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code:: python
message.add_filter('templates', 'enable', '1')
message.add_filter('templates', 'template_id', 'TEMPLATE-ALPHA-NUMERIC-ID')
message.add_substitution('key', 'value')
Tests
~~~~~
**Prerequisites:**
- Mac OS X Prerequisite:
.. code:: python
xcode-select --install
- Install pyenv and tox
.. code:: python
brew update
brew install pyenv
pip install tox
- Add `eval "$(pyenv init -)"` to your profile after installing tox, you only need to do this once.
.. code:: python
pyenv install 2.6.9
pyenv install 2.7.8
pyenv install 3.2.6
pyenv install 3.3.6
pyenv install 3.4.3
pyenv install 3.5.0
**Run the tests:**
.. code:: python
virtualenv venv
source venv/bin/activate #or . ./activate.sh
python setup.py install
pyenv local 3.5.0 3.4.3 3.3.6 3.2.6 2.7.8 2.6.9
pyenv rehash
tox
Deploying
~~~~~~~~~
- Confirm tests pass
- Bump the version in `sendgrid/version.py`
- Update `CHANGELOG.md`
- Confirm tests pass
- Commit `Version bump vX.X.X`
- `python setup.py sdist bdist_wininst upload`
- Push changes to GitHub
- Release tag on GitHub `vX.X.X`
.. _X-SMTPAPI: http://sendgrid.com/docs/API_Reference/SMTP_API/
.. _SMTPAPI Python library: https://github.com/sendgrid/smtpapi-python
.. _Substitution: http://sendgrid.com/docs/API_Reference/SMTP_API/substitution_tags.html
.. _Section: http://sendgrid.com/docs/API_Reference/SMTP_API/section_tags.html
.. _Category: http://sendgrid.com/docs/Delivery_Metrics/categories.html
.. _Unique Arguments: http://sendgrid.com/docs/API_Reference/SMTP_API/unique_arguments.html
.. _Filter: http://sendgrid.com/docs/API_Reference/SMTP_API/apps.html
.. _`Web API v3 endpoints`: https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html
.. _TOX: https://testrun.org/tox/latest/
.. _`few of the v3`: APIKeysAnchor_
.. _`Suppression Management`: https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/index.html
.. _`Global Stats`: https://sendgrid.com/docs/API_Reference/Web_API_v3/Stats/global.html
.. _`SendGrid Dashboard`: https://app.sendgrid.com/settings/api_keys
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
sendgrid-1.6.22.tar.gz
(15.6 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sendgrid-1.6.22.tar.gz.
File metadata
- Download URL: sendgrid-1.6.22.tar.gz
- Upload date:
- Size: 15.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e62bb3b6272219f1ab5d55dd0293e8eee199c1184fad109873b3cf7f45b44b2e
|
|
| MD5 |
fa1a2c9ff5a52bb6d4f57754de890a62
|
|
| BLAKE2b-256 |
0519a96da577a20e6d0520388510fb4b5b989078be18c6c6e8b5aae146dd5cb8
|
File details
Details for the file sendgrid-1.6.22.macosx-10.11-intel.exe.
File metadata
- Download URL: sendgrid-1.6.22.macosx-10.11-intel.exe
- Upload date:
- Size: 101.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b7d189c5c8f0a64c99728b1b19790c1e64e87fae9d86c26d84c11e64ee4db4b7
|
|
| MD5 |
3604d36f5a6a7e3569d1f077384d10f0
|
|
| BLAKE2b-256 |
edab13320b8f89e4d6356f1b598a66580eeac722c5356fea5d08bc417d1360d0
|
