Skip to content

Latest commit

 

History

History
317 lines (234 loc) · 6.5 KB

USAGE_v2.md

File metadata and controls

317 lines (234 loc) · 6.5 KB
Raw

INITIALIZATION

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.

sg = sendgrid.SendGridClient('YOUR_SENDGRID_API_KEY')

Table of Contents

METHODS

There are multiple ways to add recipients:

add_to

message = sendgrid.Mail()
message.add_to('[email protected]')
# or
message.add_to('Example Dude <[email protected]>')
# or
message.add_to(['Example Dude <[email protected]>', '[email protected]'])

add_to_name

message = sendgrid.Mail()
message.add_to('[email protected]')
message.add_to_name('Example Dude')

add_cc

message = sendgrid.Mail()
message.add_cc('[email protected]')
message.add_cc(['[email protected]', '[email protected]'])

add_bcc

message = sendgrid.Mail()
message.add_bcc('[email protected]')
# or
message.add_bcc(['Example Dude <[email protected]>', '[email protected]'])

set_from

message = sendgrid.Mail()
message.set_from('[email protected]')

set_from_name

message = sendgrid.Mail()
message.set_from('[email protected]')
message.set_from_name('Example Dude')

set_replyto

message.sendgrid.Mail()
message.set_replyto('[email protected]')

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 ATTACHEMENTS

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 streams

add_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.

Example

sg = sendgrid.SendGridClient('SENDGRID_API_KEY')
message = sendgrid.Mail()
message.add_substitution(':first_name', 'John')
message.smtpapi.add_to('John <[email protected]>')
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 <[email protected]>')
sg.send(message)

Recipients_

message = sendgrid.Mail()
message.smtpapi.add_to('[email protected]')

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')
message.add_substitution('key', 'value')

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('YOUR_SENDGRID_API_KEY', None, raise_errors=True)

try:
    sg.send(message)
except SendGridClientError:
    ...
except SendGridServerError:
    ...