Email API¶
Sending Emails¶
You can send emails through GatewayAPI using our email endpoint. Contact sales@gatewayapi.com to request access.
If you need SPF on your domain, you will need to include the following in your DNS SPF record: include:_spf.gatewayapi.com
POST /rest/email
¶
Request JSON Object:
- html (string) - The html content of the email
- plaintext (string) - The plain text content of the email
- subject (string) - The subject line of the email, tags can be used like in the message to personalize the subject
- from (string) - The name and email of the sender, can be just the email if no name is specified, see below for format
- reply (string) - The name and email of the sender, can be just the email if no name is specified, see below for format
- callback_url (string) - Callback URL to get status reports
- userref (string) - Add your own custom reference to be passed back to the provided callback URL
- tags (array) - A list of string tags, which will be replaced with the tag values for each recipient, if used remember to also add tagvalues to all recipients
- recipients (array) - List of email addresses to receive the email, described below:
Request JSON Array of Objects:
- address (string) - The recipient email address.
- name (string) - The name of the recipient shown in the email client.
- tagvalues (array) - A list of string values corresponding to the tags in the email. The order and amount of tag values must exactly match the tags.
- cc (array) - A list of cc recipients, takes an address and optionally a name of the recipient.
- bcc (array) - A list of cc recipients, takes an address and optionally a name of the recipient.
Status Codes:
- 200 OK - Returns an object with an array of message IDs and an object with usage information on success
- 400 Bad Request - i.e. invalid arguments, details in the JSON body
- 401 Unauthorized - i.e. invalid API key or signature
- 403 Forbidden - i.e. unauthorized IP address
- 422 Unprocessable Entity - Invalid JSON request body
- 500 Internal Server Error - If the request cannot be processed due to an exception. The exception details are returned in the JSON body
Request example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
|
Example response
If the request succeeded, the internal message identifiers are returned to the caller like this:
1 2 3 4 5 6 7 8 9 10 11 12 |
|
If you want to send attachments, encode them as base64 and add the following to the payload. The maximum total size for attachments is 5MB.
POST /rest/email
¶
Request JSON Object:
- attachments (array) - A list of base64 encoded files to be attached to the email, described below:
Request JSON Array of Objects:
- data (string) - The base64 encoded data of the file to attach.
- filename (string) - The name of the file attached to the email.
- mimetype (string) - The mimetype of the file, eg. text/csv.
Email status callback¶
If you add a callback URL to your email request, you will receive a callback with the following JSON payload. This is the same mechanism for webhooks as the SMS REST API, so check that for more details on how they function.
POST /example/callback
¶
Request JSON Object:
- id (integer) - The ID of the email this notification concerns
- time (integer) - The UNIX Timestamp for the delivery status event
- email_address (string) - The email address of the recipient
- status (string) - One of the states below, in all-caps, i.e.
DELIVERED
- userref (string) - If you specified a reference when sending the message, it is returned to you
- details (string) - If available, will contain extra information about the email with output from the SMTP server.
- callback_url (string) - The callback url provided
Status Codes:
- 200 OK - If you reply with a 2xx code, we will consider the status delivered successfully.
- 500 Internal Server Error - If we get a code >= 300, we will re-attempt delivery at a later time.
Callback example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
The status field can be of the following values.
Status | Description |
---|---|
PROCESSSED | The email has been successfully received by the system and is ready to be sent |
DELIVERED | The email was successfully delivered to the recipients inbox. |
DEFERRED | The email is delayed and will try to be sent at a later point. This typically happens if the recipient’s mail server has a temporary issue. |
BOUNCED | The email could not be delivered. Typically when the address is unknown at the server. |
BLOCKED | The email has been blocked by the server. |
Depending on the error, the states BLOCKED
and BOUNCED
will have more information in the details field.