SendGrid Python Library
Switch branches/tags
Nothing to show
Pull request Compare This branch is 664 commits behind sendgrid:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


This library allows you to quickly and easily send emails through SendGrid using Python.


Licensed under the MIT License.


Using Github:

git clone

Using Pypi:

easy_install sendgrid

SendGrid APIs

SendGrid provides two methods of sending email: the Web API, and SMTP API. SendGrid recommends using the SMTP API for sending emails. For an explanation of the benefits of each, refer to

This library implements a common interface to make it very easy to use either API.

Mail Pre-Usage

Before we begin using the library, its important to understand a few things about the library architecture...

  • Sending an email is as simple as :
    1. Creating a SendGrid Instance
    2. Creating a SendGrid Mail object, and setting its data
    3. Sending the mail using either SMTP API or Web API.

Mail Usage

import sendgrid

s = sendgrid.Sendgrid('username', 'password', secure=True)
message = sendgrid.Message("", "subject", "plain body", "<b>Html here</b>")
message.add_to("", "John Doe")




To set the "from name", you must pass the address and name in a tuple, like this:

message = sendgrid.Message(("", "Joe Smith"), "subject", "plain body", "<b>Html here</b>")

Using Categories

Categories are used to group email statistics provided by SendGrid.

To use a category, simply set the category name. Note: there is a maximum of 10 categories per email.

message = sendgrid.Message("", "subject", "plain body", "<b>Html here</b>")
message.add_category(["Category 1", "Category 2"])

Using Attachments

File attachments are limited to 7 MB per file.

message = sendgrid.Message("", "subject", "plain body", "<b>Html here</b>")
message.add_attachment("file1.doc", "/path/to/file.doc").add_attachment("file2.nfo", "File 2 content")

Using Substitutions

Substitutions can be used to customize multi-recipient emails, and tailor them for the user

message = sendgrid.Message("", "subject", "Hello %name%, your code is %code%", "<b>Hello %name%, your code is %code%</b>")
        '': {'%name%': 'Name 1', '%code%': 'Code 1'},
        '': {'%name%': 'Name 2', '%code%': 'Code 2'},

Using Sections

Sections can be used to further customize messages for the end users. A section is only useful in conjunction with a substition value.

message = sendgrid.Message("", "subject", "Hello %name%, you work at %place%",
    "<b>Hello %name%, you work at %place%</b>")
        '': {'%name%': 'Name 1', '%place%': '%home%'},
        '': {'%name%': 'Name 2', '%place%': '%office%'},
).set_sections({"%office%": "an office", "%home%": "your house"})

Using Unique Arguments

Unique Arguments are used for tracking purposes

message = sendgrid.Message("", "subject", "plain body", "<b>Html here</b>")
message.add_unique_argument("Customer", "Someone")

Using Filter Settings

Filter Settings are used to enable and disable apps, and to pass parameters to those apps.

message = sendgrid.Message("", "subject", "plain body", "<b>Html here</b>")
message.add_filter_setting("footer", "text/plain", "Here is a plain text footer")
message.add_filter_setting("footer", "text/html", "<p style='color:red;'>Here is an HTML footer</p>")

Using Headers

Custom headers can be added as necessary.

message = sendgrid.Message("", "subject", "plain body", "<b>Html here</b>")
message.add_header("X-Mailer", "MyApp")