Skip to content

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 personalise 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:

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
POST /rest/email HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjoK
Accept: application/json, text/javascript
Content-Type: application/json

{
    "html": "<b>Hello %firsname %surname %target is about to be removed.",
    "plaintext": "Hello %firsname %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 succeed, the internal message identifiers are returned to the caller like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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 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

Example of how our request to you could look like.

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, ie. 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
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
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.