This library allows you to quickly and easily send emails through SendGrid using Python.
Licensed under the MIT License.
Using Github:
git clone git@github.com:sendgrid/sendgrid-python.git
Using Pypi:
easy_install sendgrid
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 http://docs.sendgrid.com/documentation/get-started/integrate/examples/smtp-vs-rest/.
This library implements a common interface to make it very easy to use either API.
Before we begin using the library, its important to understand a few things about the library architecture...
- Sending an email is as simple as :
- Creating a SendGrid Instance
- Creating a SendGrid Mail object, and setting its data
- Sending the mail using either SMTP API or Web API.
import sendgrid
s = sendgrid.Sendgrid('username', 'password', secure=True)
message = sendgrid.Message("from@mydomain.com", "subject", "plain body", "<b>Html here</b>")
message.add_to("someone@example.com", "John Doe")
s.web.send(message)Or
s.smtp.send(message)To set the "from name", you must pass the address and name in a tuple, like this:
message = sendgrid.Message(("from@mydomain.com", "Joe Smith"), "subject", "plain body", "<b>Html here</b>")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("from@mydomain.com", "subject", "plain body", "<b>Html here</b>")
message.add_category(["Category 1", "Category 2"])File attachments are limited to 7 MB per file.
message = sendgrid.Message("from@mydomain.com", "subject", "plain body", "<b>Html here</b>")
message.add_attachment("file1.doc", "/path/to/file.doc").add_attachment("file2.nfo", "File 2 content")Substitutions can be used to customize multi-recipient emails, and tailor them for the user
message = sendgrid.Message("from@mydomain.com", "subject", "Hello %name%, your code is %code%", "<b>Hello %name%, your code is %code%</b>")
message.add_to(
{
'example1@example.com': {'%name%': 'Name 1', '%code%': 'Code 1'},
'example2@example.com': {'%name%': 'Name 2', '%code%': 'Code 2'},
}
)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("from@mydomain.com", "subject", "Hello %name%, you work at %place%",
"<b>Hello %name%, you work at %place%</b>")
message.add_to(
{
'example1@example.com': {'%name%': 'Name 1', '%place%': '%home%'},
'example2@example.com': {'%name%': 'Name 2', '%place%': '%office%'},
}
).set_sections({"%office%": "an office", "%home%": "your house"})Unique Arguments are used for tracking purposes
message = sendgrid.Message("from@mydomain.com", "subject", "plain body", "<b>Html here</b>")
message.add_unique_argument("Customer", "Someone")Filter Settings are used to enable and disable apps, and to pass parameters to those apps.
message = sendgrid.Message("from@mydomain.com", "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>")Custom headers can be added as necessary.
message = sendgrid.Message("from@mydomain.com", "subject", "plain body", "<b>Html here</b>")
message.add_header("X-Mailer", "MyApp")