Menu
Amazon Simple Email Service
Developer Guide (API Version 2010-12-01)

Query Requests and Amazon SES

Amazon SES supports Query requests for service actions. Query requests are simple HTTPS requests that use the GET or POST method. Query requests must contain an Action parameter to indicate the action to be performed.

Important

For security reasons, Amazon SES does not support HTTP requests. You must use HTTPS instead.

Structure of a GET Request

This guide presents the Amazon SES GET requests as URLs. Each URL consists of the following:

  • Endpoint—The resource the request is acting on. For a list of Amazon SES endpoints, see Regions and Amazon SES.

  • Action—The action you want to perform on the endpoint, such as sending a message.

  • Parameters—Any request parameters.

The following is an example GET request to send a message using the Amazon SES endpoint in the US West (Oregon) region.

Copy
https://email.us-west-2.amazonaws.com?Action=SendEmail&Source=user%40example.com&Destination.ToAddresses.member.1=allan%40example.com&Message.Subject.Data=This%20is%20the%20subject%20line.&Message.Body.Text.Data=Hello.%20I%20hope%20you%20are%20having%20a%20good%20day.

Important

Because the GET requests are URLs, you must URL-encode the parameter values. For example, in the preceding example request, the value for the Source parameter is actually user@example.com. However, the "@" character is not allowed in URLs, so each "@" is URL-encoded as "%40".

To make the GET examples easier to read, this guide presents them in the following parsed format.

Copy
https://email.us-west-2.amazonaws.com ?Action=SendEmail &Source=user%40example.com &Destination.ToAddresses.member.1=allan%40example.com &Message.Subject.Data=This%20is%20the%20subject%20line. &Message.Body.Text.Data=Hello.%20I%20hope%20you%20are%20having%20a%20good%20day.

The first line represents the endpoint of the request. After the endpoint is a question mark (?), which separates the endpoint from the parameters. Each parameter is separated by an ampersand (&).

The Action parameter indicates the action to perform. For a complete list of actions, and the parameters used with each action, see the Amazon Simple Email Service API Reference.

Some operations take lists of parameters. For example, when you send an email to multiple recipients, you can provide a list of email addresses. You specify this type of list with param.n notation, where values of n are integers starting from 1. For example, you would specify the first "To:" address using Destination.ToAddresses.1, the second with Destination.ToAddresses.2, etc.

In Amazon SES, spaces are not allowed in any of the parameter values. In this guide, any example Query request parameter value that includes spaces is displayed in one of two different ways:

  • URL-encoded (as %20).

  • Represented by a plus sign ("+"). Within a Query request, a plus sign is reserved as a shorthand notation for a space. (If you want to include a literal, uninterpreted plus sign in any parameter, you must URL-encode it as %2B.)

Note

Every request must be accompanied by an X-Amzn-Authorization HTTP header. For more information, see Request Authentication and Amazon SES.

Structure of a POST Request

Amazon SES also accepts POST requests. With a POST request, you send the query parameters as a form in the HTTP request body as described in the following procedure.

To create a POST request

  1. Assemble the query parameter names and values into a form.

    Put the parameters and values together as you would for a GET request (with an ampersand separating each name-value pair). The following example shows a SendEmail request with the line breaks we use in this guide to make the information easier to read.

    Copy
    Action=SendEmail &Source=user@example.com &Destination.ToAddresses.member.1=allan@example.com &Message.Subject.Data=This is the subject line. &Message.Body.Text.Data=Hello. I hope you are having a good day.

  2. Form-URL-encode the form according to the Form Submission section of the HTML specification.

    For more information, see http://www.w3.org/MarkUp/html-spec/html-spec_toc.html#SEC8.2.1.

    Copy
    Action=SendEmail &Source=user%40example.com &Destination.ToAddresses.member.1=allan%40example.com &Message.Subject.Data=This%20is%20the%20subject%20line. &Message.Body.Text.Data=Hello.%20I%20hope%20you%20are%20having%20a%20good%20day.
  3. Provide the resulting form as the body of the POST request.

  4. Include the following HTTP headers in the request:

  5. Send the completed request.

    Copy
    POST / HTTP/1.1 Date: Thu, 26 May 2011 06:49:50 GMT Host: email.us-west-2.amazonaws.com Content-Type: application/x-www-form-urlencoded X-Amzn-Authorization: AWS3 AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE,Signature=lBP67vCvGlDMBQ=dofZxg8E8SUEXAMPLE,Algorithm=HmacSHA256,SignedHeaders=Date;Host Content-Length: 230 Action=SendEmail &Source=user%40example.com &Destination.ToAddresses.member.1=allan%40example.com &Message.Subject.Data=This%20is%20the%20subject%20line. &Message.Body.Text.Data=Hello.%20I%20hope%20you%20are%20having%20a%20good%20day.

The X-Amzn-Authorization header you provide is the same header you would provide if you sent a GET request.

Note

Your HTTP client typically adds other items to the HTTP request as required by the version of HTTP that the client uses. We don't include those additional items in the examples in this guide.