Skip to main content

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

Project details


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 hashes)

Uploaded Source

Built Distribution

sendgrid-1.6.22.macosx-10.11-intel.exe (101.0 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page