Amazon simple email service (AWS SES) simplified and explained with a PHP example

Cloud computing has truly made infrastructure accessible to the whole spectrum of professionals. Whether you are a recreational user, a small startup or a multinational giant, you can leave the burden of hardware, storage and network infrastructure management to the experts. Unless of course you happen to be in the business of providing such services yourself. While the cloud has made infrastructure accessible, some cloud service providers have really taken that to the next level and broken it down to bite size pieces. Now you can pay for exactly what you consume, and then consume as much or as little as you want / need. You can keep all of your services and more configured, you pay only when you launch a service and for the time it remains live. Think about scaling – you can now have all the infrastructure you need - configured and ready, and scale up or down on demand. However, having said that, until very recently I was not able to find an email transport service that would match the same characteristics – easily accessible, scalable, bite sized and affordable.

Then, around January of 2011, Amazon announced the simple email service (popularly known as SES). The pricing - most attractive - a few cents per thousand email messages sent, simple as that. Can't beat that really; especially when you consider traditional costs like upfront charges, licensing, operating costs, minimum usage charges, contract periods, etc. Additionally, a customer can send a couple thousand email messages for free each day when these emails originate from Amazon's own cloud (EC2 or AWS Elastic Beanstalk). This last bit is obviously designed to create some customer stickiness, but with the model they are building – I for one, am certainly not complaining.

Overjoyed at the launch I went straight to to the site and got started (well, correction – tried to get started). On exploring the documentation and the API for some time, I can't claim to have had a flying start. Everything felt simple and within reach, but nevertheless I seemed to keep stumbling from one thing to the other. After a good deal of research and other ground work, I have since been able to make sense of the service and now have successful applications in production that consume SES. This article is an attempt at giving back to the community and making things simpler for folks that are toying with SES now and want to give it a try.

What is the service?

The Simple Email Service is an electronic mail transport mechanism, that is exposed through a web services API. In layman terms, if you are a developer of software application that need to send e-mails to users or administrators, you would need to use this service or some other similar service. The SES is an extension of the sophisticated email infrastructure Amazon has built to serve its own large-scale customer base. It is a high-quality, scalable email infrastructure with built-in feedback tools that provide metrics which one would need in order to monitor quality of emails.

What the service is not?

This service is not an email program that provides you with an e-mail address and sends or stores email messages for you.

What do you need to start?

1. You will have to first “sign up for Amazon SES” (search for the quoted string to get to the web location).

2. Once you are signed up, request an access key and a secret key. This key pair will give you access to all Amazon services and is associated with the registration you created with Amazon (store the key pair securely). In case you are already an AWS (Amazon Web Services) user, you are likely to already have a key pair. You can continue to use the same for SES as well.

3. You can now access the Amazon SES sandbox – development area (I will explain some of these in greater detail below so just read on).

4. To access the sandbox and the (production environment later), you will need a good class library that has been thoughtfully created with appropriate functions to make use of all the SES API services. Here is (the download page for) a PHP class library created by Dan Myers that expertly exposes all the SES services: get it here

That is all you need to start out with. However, there is a little more prep work to do. The sandbox environment does not allow you to send e-mails to or form e-mail ids that you do not have direct access to. You will need to verify the the addresses before you can send or receive e-mail. Once you move on to the production environment (which is after all of your test work is complete – I will explain) you will then only need “from” e-mail addresses to be verified. “To” e-mail addresses will not need verification any more.

5.To verify an email addresses, make an API call with the email address as a parameter. This API call will trigger a verification email to the said e-mail address, which will contain a link that you can click on to complete the verification process.

Here is a PHP code snippet using Dan's class that will get you through the address verification process:

// include the SES class
require_once('ses.php');
$aws_access_key='xyz' //replace 'xyz' with your aws access key
$aws_secret_key='abc' //replace 'abc' with your aws serect key

// create a SimpleEmailService class object
$aws_ses = new SimpleEmailService($aws_access_key, $aws_secret_key);

//Verify the address and print the response (replace user_to@example.com with your first test e-mail address)
print_r($aws_ses->verifyEmailAddress('user_to@example.com'));
//Verify the address and print the response (replace user_from@example.com with your second test e-mail address)
print_r($aws_ses->verifyEmailAddress('user_from@example.com'));

The print_r call will produce a request id returned by the SimpleEmailService. Actually the service will return a request id for every service request. When the above call succeeded, you should receive e-mails from AWS at the e-mail ids provided. These e-mails will each contain a link that you need to click on to complete the verification process.

6.Once the verification process is complete, you can check the verified e-mails by making the following call:
print_r($aws_ses->listVerifiedEmailAddresses());

7.Verify all the emails that will be used in the sand box in this fashion. You are now done with most of the confusing parts of the API and its implementation.

8.Removing an e-mail from your verified list can be easy as well, just make the following call with the correct e-mail:
$aws_ses->deleteVerifiedEmailAddress('user@example.com');

9.Sending the first (SMTP compliant) e-mail message:

a)First create a SimpleEmailServiceMessage object (over and above the SimpleEmailService class object created earlier)
$message = new SimpleEmailServiceMessage();

b)Then build up the Message as follows:
$message->addTo('user_to@example.com');
$message->addCC('user_cc@example.com');
$message->addBCC('user_bcc@example.com');
$message->setFrom('user_from@example.com');
$message->setSubject('Hello, world!');
$message->setMessageFromString('This is the message body.');

c)Got a HTML message body as well? Replace the setMessageFromString with the following:
$message->setMessageFromString($text, $html); //$text and $html obviously containing the two types of messages.

d)To add a return path use:
$message->setReturnPath('return_path@example.com');

e)To add a reply to address use:
$message->addReplyTo('reply_to@example.com');

f)Finally send the e-mail as follows:
$aws_ses->sendEmail($message);

g)Putting it all together:
// include the SES class
require_once('ses.php');
$aws_access_key='xyz' //replace 'xyz' with your aws access key
$aws_secret_key='abc' //replace 'abc' with your aws serect ksy

// create a SimpleEmailService class object
$aws_ses = new SimpleEmailService($aws_access_key, $aws_secret_key);

// create a SimpleEmailServiceMessage object
$message = new SimpleEmailServiceMessage();

//build up the Message
$message->addTo('user_to@example.com');//remember to use correct email ids
$message->addCC('user_cc@example.com');
$message->addBCC('user_bcc@example.com');
$message->setFrom('user_from@example.com');
$message->setReturnPath('return_path@example.com');
$message->addReplyTo('reply_to@example.com');
$message->setSubject('Hello, world!');
$message->setMessageFromString('This is the message body.');

//send the e-mail
$aws_ses->sendEmail($message);

10.Now that you have sent the first e-mail message, you can make informational queries:
print_r($aws_ses->getSendQuota());
// Tells you how may e-mails you will be able to send per day and how many in any given second. AWS will ramp up the initial limit for you as you continue to use the service.
print_r($aws_ses->getSendStatistics());
// Tells you the number of e-mails sent in the last 24 hours, total number of messages sent, bounces, rejects and complaints.

11.check the e-mail-ids for the e-mails you sent. Your e-mail transport should now be working.

12.Now you are ready to use Amazon SES to send email, you should request production access (go to the aws site to do so). This will allow you to move from the sandbox environment to the production environment and begin sending email to your customers. It takes a few minutes to apply for production access, and you usually receive a response within 24 hours.

13.You will still need verified e-mail-ids to send e-mail from.

14.You will now be able to send e-mails to unverified e-mail-ids.

So now you should be (or could be) up and running with AWS SES. Pass this article on to anyone that you think is like you or me, and could use some basic information put together in one place.

Before I close, I want to let you know that (at the time of writing this article) I do not work for Amazon or get paid by them in anyway – I am just another user and a fan of their cloud based services. I would also like to thank Dan Myers – I have referred to his open source PHP class in this article – keep up the good work Dan.



Author:  Rajiv Banerjee   careersngigs.com           
Page: End

Search