Email API

You can send emails through GatewayAPI using our email endpoint. Contact sales@gatewayapi.com to request access.

DNS setup

If you are using our email service with our partner Heysender, you need to create two DNS records for SPF and DKIM for the domains you want to use. This is usually done through an administrative interface for your domain.

SPF

If you already have an SPF record for your domain, you will need to include include:_spf.gatewayapi.com like:

v=spf1 include:spf.example.com include:_spf.gatewayapi.com ~all

If you do not have an existing record, you need to create a TXT DNS record for your domain:

v=spf1 include:_spf.gatewayapi.com ~all

DKIM

To get DKIM you also need to create a TXT DNS record, but the domain portion of the record will need to be prepended with heysender._domainkey. If your domain is example.com it will be heysender._domainkey.example.com. The correct value of the TXT record will be supplied to you by our support team, the example below is just an example:

 k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC2Cq98WEZilv3fkF2kLdEpYH7SSc8kkGHWBLI5lonukA8SZpAGfmiHkDuMNubd+5Qg4rmS6cecowBQ+60SVI/ogHzLAAkWFFJ94CUDreA8u4cwGUnKhuN6fwk1OVyQZTfncMFp1H+6R56fcOLf33uaaJBvPv1VHazVHP2UxXdgyQIDAQAB

Once you have setup both DNS records for your email sending domain, report back to our support team who will be able to verify the records and enable your email traffic.

Sending Emails

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

POST /rest/email HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjoK
Accept: application/json, text/javascript
Content-Type: application/json

{
    "html": "<b>Hello %firstname %surname %target is about to be removed.",
    "plaintext": "Hello %firstname %surname %target is about to be removed.",
    "subject": "Annihilation: %target",
    "from": "Darth Vader <darth@example.com>",
    "reply": "bounce@example.com",
    "tags": ["%firstname", "%surname", "%target"],
    "recipients": [
        {
            "address": "l.organa@example.com",
            "name": "Leia Organa",
            "tagvalues": ["Leia", "Organa", "Alderaan"],
            "cc": [
                {
                    "address": "h.solo@example.com",
                    "name": "Han Solo"
                }
            ],
            "bcc": [
                {
                    "address": "chewie@example.com",
                    "name": "Chewbacca"
                }
            ]
        },
        {
            "address": "l.skywalker@example.com",
            "name": "Luke Skywalker",
            "tagvalues": ["Luke", "Skywalker", "Alderaan"]
        }
    ],
    "attachments": [
        {
            "data": "/9j/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/yQALCAABAAEBAREA/8wABgAQEAX/2gAIAQEAAD8A0s8g/9k=",
            "filename": "kyber.jpeg",
            "mimetype": "image/jpeg"
        }
    ]
}

Example response

If the request succeeded, the internal message identifiers are returned to the caller like this:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ids": [431332671]
    "usage": {
        "amount": 4,
        "currency": "DKK",
        "total_cost": 0.003
    }

}

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

POST /example/callback HTTP/1.1
Host: example.com
Accept: */*
Content-Type: application/json

{
    "id": 1000001,
    "time": 1450000000,
    "email_address": "example@test.com",
    "status": "DELIVERED",
    "userref": "foobar",
    "details": "250 2.0.0 OK",
    "callback_url": "https://example.com/example/callback",
}

The status field can be of the following values.

Status	Description
PROCESSED	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.