SendGrid library for Python
Project description
This library allows you to quickly and easily send emails through SendGrid using 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.
Install
pip install sendgrid
# or
easy_install sendgridExample
import sendgrid
sg = sendgrid.SendGridClient('YOUR_SENDGRID_USERNAME', 'YOUR_SENDGRID_PASSWORD')
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.
from sendgrid import SendGridError, SendGridClientError, SendGridServerError
sg = sendgrid.SendGridClient(username, password, 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 credentials or a SendGrid API Key. API Key is the preferred method. API Keys are in beta. To configure API keys, visit https://app.sendgrid.com/settings/api_keys.
sg = sendgrid.SendGridClient('sendgrid_username', 'sendgrid_password')
# or
sg = sendgrid.SendGridClient('sendgrid_apikey')Methods
There are multiple ways to add recipients:
add_to
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
message = sendgrid.Mail()
message.add_to('example@email.com')
message.add_to_name('Example Dude')add_cc
message = sendgrid.Mail()
message.add_cc('example@email.com')
message.add_cc(['example@email.com', 'john@email.com'])add_bcc
message = sendgrid.Mail()
message.add_bcc('example@email.com')
# or
message.add_bcc(['Example Dude <example@email.com>', 'john@email.com'])set_from
message = sendgrid.Mail()
message.set_from('example@email.com')set_from_name
message = sendgrid.Mail()
message.set_from('example@email.com')
message.set_from_name('Example Dude')set_replyto
message.sendgrid.Mail()
message.set_replyto('example@email.com')set_subject
message = sendgrid.Mail()
message.set_subject('Example')set_text
message = sendgrid.Mail()
message.set_text('Body')set_html
message = sendgrid.Mail()
message.set_html('<html><body>Stuff, you know?</body></html>')set_date
message = sendgrid.Mail()
message.set_date('Wed, 17 Dec 2014 19:21:16 +0000')set_headers
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
message = sendgrid.Mail()
message.add_attachment('stuff.txt', './stuff.txt')
# or
message.add_attachment('stuff.txt', open('./stuff.txt', 'rb'))add_attachment_stream
message = sendgrid.Mail()
message.add_attachment_stream('filename', 'somerandomcontentyouwant')
# strings, unicode, or BytesIO streamsadd_content_id
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>')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.
Recipients
message = sendgrid.Mail()
message.smtpapi.add_to('example@email.com')Substitution
message = sendgrid.Mail()
message.smtpapi.add_substitution('key', 'value')add_substitution
message = sendgrid.Mail()
message.add_substitution('key', 'value')set_substitutions
message = sendgrid.Mail()
message.set_substitutions({'key1': ['value1', 'value2'], 'key2': ['value3', 'value4']})Section
message = sendgrid.Mail()
message.smtpapi.add_section('section', 'value')add_section
message = sendgrid.Mail()
message.add_section('section', 'value')set_sections
message = sendgrid.Mail()
message.set_sections({'section1': 'value1', 'section2': 'value2'})Category
message = sendgrid.Mail()
message.smtpapi.add_category('category')add_category
message = sendgrid.Mail()
message.add_category('category')set_categories
message = sendgrid.Mail()
message.set_categories(['category1', 'category2'])Unique Arguments
message = sendgrid.Mail()
message.smtpapi.add_unique_arg('key', 'value')add_unique_arg
message = sendgrid.Mail()
message.add_unique_arg('key', 'value')set_unique_args
message = sendgrid.Mail()
message.set_unique_args({'key1': 'value1', 'key2': 'value2'})Filter
message = sendgrid.Mail()
message.smtpapi.add_filter('filter', 'setting', 'value')add_filter
message = sendgrid.Mail()
message.add_filter('filter', 'setting', 'value')ASM Group
message = sendgrid.Mail()
message.smtpapi.set_asm_group_id(value)set_asm_group_id
message = sendgrid.Mail()
message.set_asm_group_id(value)Using Templates from the Template Engine
message.add_filter('templates', 'enable', '1')
message.add_filter('templates', 'template_id', 'TEMPLATE-ALPHA-NUMERIC-ID')Tests
virtualenv venv
source venv/bin/activate
python setup.py install
python test/__init__.pyDeploying
Confirm tests pass
Bump the version in README.rst, 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
MIT License
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
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.4.3.tar.gz.
File metadata
- Download URL: sendgrid-1.4.3.tar.gz
- Upload date:
- Size: 8.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
346498896b14a1e0c3545b64f4a81a6d8358001f81cf0c0cf72e74f4bcbfb25e
|
|
| MD5 |
6c70a5b7dffa4e1cb093b436431e11d4
|
|
| BLAKE2b-256 |
be3b325b1937dc5ec1f3fe86c0b647b67c53e91b1d770f46adf28fd39d5c3e78
|
File details
Details for the file sendgrid-1.4.3.macosx-10.10-x86_64.exe.
File metadata
- Download URL: sendgrid-1.4.3.macosx-10.10-x86_64.exe
- Upload date:
- Size: 80.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
40128e74019b73022115d08235b206a19271efa5ba4d953ad0fb2e43a9e7cad5
|
|
| MD5 |
d0b96f26fe61bb38c5469b79dc971073
|
|
| BLAKE2b-256 |
23a840c29f7bf997ddce184f68e5979d46a34776ac711ce7e141891ffa310a62
|
