PageRenderTime 22ms CodeModel.GetById 14ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 1ms

/boto-2.5.2/docs/source/ses_tut.rst

#
ReStructuredText | 171 lines | 141 code | 30 blank | 0 comment | 0 complexity | 301b088d5c6c45f78203283b1c7dc5ae MD5 | raw file
  1.. ses_tut:
  2
  3=============================
  4Simple Email Service Tutorial
  5=============================
  6
  7This tutorial focuses on the boto interface to AWS' `Simple Email Service (SES) <ses>`_.
  8This tutorial assumes that you have boto already downloaded and installed.
  9
 10.. _SES: http://aws.amazon.com/ses/
 11
 12Creating a Connection
 13---------------------
 14
 15The first step in accessing SES is to create a connection to the service.
 16To do so, the most straight forward way is the following::
 17
 18    >>> import boto
 19    >>> conn = boto.connect_ses(
 20            aws_access_key_id='<YOUR_AWS_KEY_ID>',
 21            aws_secret_access_key='<YOUR_AWS_SECRET_KEY>')
 22    >>> conn
 23    SESConnection:email.us-east-1.amazonaws.com
 24
 25Bear in mind that if you have your credentials in boto config in your home
 26directory, the two keyword arguments in the call above are not needed. More
 27details on configuration can be fond in :doc:`boto_config_tut`.
 28
 29The :py:func:`boto.connect_ses` functions returns a
 30:py:class:`boto.ses.connection.SESConnection` instance, which is a the boto API
 31for working with SES.
 32
 33Notes on Sending
 34----------------
 35
 36It is important to keep in mind that while emails appear to come "from" the
 37address that you specify via Reply-To, the sending is done through Amazon.
 38Some clients do pick up on this disparity, and leave a note on emails.
 39
 40Verifying a Sender Email Address
 41--------------------------------
 42
 43Before you can send email "from" an address, you must prove that you have
 44access to the account. When you send a validation request, an email is sent
 45to the address with a link in it. Clicking on the link validates the address
 46and adds it to your SES account. Here's how to send the validation email::
 47
 48    >>> conn.verify_email_address('some@address.com')
 49    {
 50        'VerifyEmailAddressResponse': {
 51            'ResponseMetadata': {
 52                'RequestId': '4a974fd5-56c2-11e1-ad4c-c1f08c91d554'
 53            }
 54        }
 55    }
 56
 57After a short amount of time, you'll find an email with the validation
 58link inside. Click it, and this address may be used to send emails.
 59
 60Listing Verified Addresses
 61--------------------------
 62
 63If you'd like to list the addresses that are currently verified on your
 64SES account, use
 65:py:meth:`list_verified_email_addresses <boto.ses.connection.SESConnection.list_verified_email_addresses>`::
 66
 67    >>> conn.list_verified_email_addresses()
 68    {
 69        'ListVerifiedEmailAddressesResponse': {
 70            'ListVerifiedEmailAddressesResult': {
 71                'VerifiedEmailAddresses': [
 72                    'some@address.com',
 73                    'another@address.com'
 74                ]
 75            },
 76            'ResponseMetadata': {
 77                'RequestId': '2ab45c18-56c3-11e1-be66-ffd2a4549d70'
 78            }
 79        }
 80    }
 81
 82Deleting a Verified Address
 83---------------------------
 84
 85In the event that you'd like to remove an email address from your account,
 86use
 87:py:meth:`delete_verified_email_address <boto.ses.connection.SESConnection.delete_verified_email_address>`::
 88
 89    >>> conn.delete_verified_email_address('another@address.com')
 90
 91Sending an Email
 92----------------
 93
 94Sending an email is done via
 95:py:meth:`send_email <boto.ses.connection.SESConnection.send_email>`::
 96
 97    >>> conn.send_email(
 98            'some@address.com',
 99            'Your subject',
100            'Body here',
101            ['recipient-address-1@gmail.com'])
102    {
103        'SendEmailResponse': {
104            'ResponseMetadata': {
105                'RequestId': '4743c2b7-56c3-11e1-bccd-c99bd68002fd'
106            },
107            'SendEmailResult': {
108                'MessageId': '000001357a177192-7b894025-147a-4705-8455-7c880b0c8270-000000'
109            }
110        }
111    }
112
113If you're wanting to send a multipart MIME email, see the reference for
114:py:meth:`send_raw_email <boto.ses.connection.SESConnection.send_raw_email>`,
115which is a bit more of a low-level alternative.
116
117Checking your Send Quota
118------------------------
119
120Staying within your quota is critical, since the upper limit is a hard cap.
121Once you have hit your quota, no further email may be sent until enough
122time elapses to where your 24 hour email count (rolling continuously) is
123within acceptable ranges. Use
124:py:meth:`get_send_quota <boto.ses.connection.SESConnection.get_send_quota>`::
125
126    >>> conn.get_send_quota()
127    {
128        'GetSendQuotaResponse': {
129            'GetSendQuotaResult': {
130                'Max24HourSend': '100000.0',
131                'SentLast24Hours': '181.0',
132                'MaxSendRate': '28.0'
133            },
134            'ResponseMetadata': {
135                'RequestId': u'8a629245-56c4-11e1-9c53-9d5f4d2cc8d3'
136            }
137        }
138    }
139
140Checking your Send Statistics
141-----------------------------
142
143In order to fight spammers and ensure quality mail is being sent from SES,
144Amazon tracks bounces, rejections, and complaints. This is done via
145:py:meth:`get_send_statistics <boto.ses.connection.SESConnection.get_send_statistics>`.
146Please be warned that the output is extremely verbose, to the point
147where we'll just show a short excerpt here::
148
149    >>> conn.get_send_statistics()
150    {
151        'GetSendStatisticsResponse': {
152            'GetSendStatisticsResult': {
153                'SendDataPoints': [
154                    {
155                        'Complaints': '0',
156                        'Timestamp': '2012-02-13T05:02:00Z',
157                        'DeliveryAttempts': '8',
158                        'Bounces': '0',
159                        'Rejects': '0'
160                    },
161                    {
162                        'Complaints': '0',
163                        'Timestamp': '2012-02-13T05:17:00Z',
164                        'DeliveryAttempts': '12',
165                        'Bounces': '0',
166                        'Rejects': '0'
167                    }
168                ]
169            }
170        }
171    }