Use the Messaging API to send personalized email for marketing, transactional, and customer-engagement workflows.

The API uses Amazon SES and supports practices that help protect deliverability and authenticate your sending domain.

Email Onboarding

Verify your sender email address before you send email through the Messaging API.

Step 1: Sender Email Verification

1. Contact the Support Team.
2. Provide the email address that you want to use as the sender.
3. Wait for the Support Team to initiate verification.

Step 2: Amazon SES Authorization

After Support submits the verification request, Amazon Web Services (SES) sends an automated email with a confirmation link.

1. Open the email from Amazon SES.
2. Select the verification link to confirm your sender address.
3. Send email through the API after SES approves the address.

Read Email Best Practices before you send email. Monitor hard bounces and remove hard-bouncing addresses from recipient lists. A high hard-bounce rate can reduce deliverability, and your account could be suspended from sending email when the bounce rate reaches 5% or higher.

Sending Email

After your sender address is verified, send email through the Messaging API.

📘

NOTE

The total number of API Calls (requests) that the user can make to this endpoint in a certain time has been limited. That is, in case the user exceeds the limit of requests (messages sent) that can be made in a specific time, they will not be able to send another request until the established time is up. Once the time has elapsed, the request counter is reset and the request can be sent to the endpoint again.

In this example, the user can send 2 requests in 300 seconds (5 minutes). When a third request is sent within the 5 minute range, the HTTP Status Code "429" will be generated and the following parameter will be displayed from the Response body: "errors": { "reason": "Too Many Requests" }. This code tells you that the user has sent too many requests in a given amount of time. Once the required time has elapsed, the request counter is reset to 2, so the user will be able to send two requests again in 5 minutes.

To find out if the user exceeds the limit of required requests and the time they needs to wait to send the next request, we recommend consulting the Response Header (additional information about the body of the resource). The parameters presented in the response header are the following:

ratelimit-limit: 2\ ratelimit-policy: 2;w= 300\ ratelimit-remaining: 1\ ratelimit-reset: 5m0s

• RateLimit-Limit: return the number of requests left for the client in the time window
• RateLimit-Remaining: return the remaining quota in the current window
• RateLimit-Reset: return the time remaining in the current window, specified in seconds
• RateLimit-Policy: return the quota policy. The quota policy expression can be found in paragraph 2.1 of the IETF draft. The format is, for example, for 2 requests in 300 seconds.

Send an email message with POST / notification. The request body is shown below.

{
  "channel": "EMAIL",
  "request": {
    "from": "[email protected]",
    "to": "[email protected]",
    "message": "Hi, this is a new promotion for November!",
    "subject": "Email Subject"
  },
  "callbacks": [
    "http://www.mycallback.com?id=123"
  ]
}

The parameters presented in the request body example when sending the Email are the following:

After the API accepts the email notification message, it returns the following response body:

{
  "meta": {
    "timestamp": 1642531254980,
    "transactionId": "077da1d0-e089-487e-aed0-59534ba2d9f5",
    "explain": "Send Notification"
  }
}

The parameters presented in the response body example when sending the Email notification message are the following:

The Messaging API publishes the email message to the Email API queue. The response therefore includes the meta segment.