Send Transactional Email

Transactional emails are once-off emails to one or more recipients. Our API supports the sending of a custom template to one or more contacts. A custom template is a raw HTML string that’s defined in the body of your request.

Transactional email templates can also be created and stored using the transactional interface. After publishing these templates, the template ID can be referenced in the options field of the request body.

Engagement can be tracked when a contact:

  • Opens transactional emails
  • Interacts with links in transactional emails
  • Opens an attached file

Engagement reports can then be viewed in our reports interface, offering valuable insights into how contacts interact with your transactional emails. These metrics aid in formulating and refining your communication strategy.

Endpoint

Method URL
POST https://api.everlytic.net/transactional/email/v1/mail

Request Body

Request with HTML provided in body

{
  "body": {
    "html": "string",
    "text": "string",
    "personalisation_fields": {
      "common_fields": {
      "string": "string"
    },
      "unique_fields": [
        {
          "[email protected]": {
      "string":"string"
      }
        }
      ]
    }
  },
  "headers": {
    "subject": "string",
    "message_id": "string",
    "from": {
      "email": "string",
      "name": "string"
    },
    "to": [
      {
        "email": "string",
        "name": "string"
      }
    ],
    "reply_to": {
      "email": "string",
      "name": "string"
    },
    "cc": [
      {
        "email": "string",
        "name": "string"
      }
    ],
    "bcc": [
      {
        "email": "string",
        "name": "string"
      }
    ],
    "custom_headers": {
      "X-Custom-Header-Name": [
        "string"
      ]
    }
  },
  "options": {
    "group_name": "string",
    "template_id": "string",
    "track_opens": boolean,
    "track_links": boolean
  },
  "attachments": {
    "data": [
      {
        "filename": "string",
        "data": "",
        "path": "string",
        "content_id": "string"
      }
    ],
    "options": {
      "track": boolean
    }
  }
}

Request using template ID

{
  "headers": {
    "to": [
      {
        "email": "string",
        "name": "string"
      }
    ],
    "cc": [
      {
        "email": "string",
        "name": "string"
      }
    ],
    "bcc": [
      {
        "email": "string",
        "name": "string"
      }
    ]
  },
  "options": {
    "group_name": "string",
    "template_id": "string"
  },
  "attachments": {
    "data": [
      {
        "filename": "string",
        "data": "",
        "path": "string",
        "content_id": "string"
      }
    ],
    "options": {
      "track": boolean
    }
  }
}

Redirect user to URL after unsubscribing

{
  "body": {
    "html": "string",
    "text": "string",
    "personalisation_fields": {
      "common_fields": {
      "string": "string"
    },
      "unique_fields": [
        {
          "[email protected]": {
      "string":"string"
      }
        }
      ]
    }
  },
  "headers": {
    "subject": "string",
    "message_id": "string",
    "from": {
      "email": "string",
      "name": "string"
    },
    "to": [
      {
        "email": "string",
        "name": "string"
      }
    ],
    "reply_to": {
      "email": "string",
      "name": "string"
    }
  },
  "options": {
    "unsubscribe_redirect_url": "string"
  }
}

Properties

Property Field Description Data type Parameters Required
body html The HTML body of the email to be sent string Yes, if options.template_id field is empty
text The text body of the email to be sent string No
personalisation_fields Custom tags that can be used to personalise emails Array
  • common_fields
  • unique_fields
 No
  • common_fields
 Tags that are intended to be the same for all recipients of the email. Array [Key]:[Value] No
  • unique_fields
 Tags that are mapped to each recipient’s email address and will be customised accordingly. Array email_address: [Key]:Value] No
headers subject Subject line of the email to be sent string Yes, if options.template_id is empty
message_id string No
from The field that specifies the email and name that the email comes from Array
  • email
  • name
 Yes, if options.template_id is empty
  • email
 The email address that will appear in the “from” field of the recipient’s inbox string Yes, if options.template_id is empty
  • name
 The name that will appear in the “from” field of the recipient’s inbox string No
to Array containing the email addresses and names of all recipients Array
  • email
  • name
 Yes
  • email
 The email address of the recipient string Yes
  • name
 The name specified for the recipient string No
reply_to The field that specifies to which email addresses replies should be sent to Array
  • email
  • name
 No
  • email
 The email address that will be receiving the replies. string No
  • name
 The name specified for the email address that will receive the replies string No
cc Array containing the email addresses of recipient that will be carbon-copied upon sending Array
  • email
  • name
 No
  • email
 Email address of the email address being cc’d. string No
  • name
 The name specified of the email address being cc’d string No
bcc Array containing the email addresses of recipient that will be blind-carbon-copied upon sending Array
  • email
  • name
 No
  • email
 Email address of the person being bcc’d. string No
  • name
 The name specified of the email address being bcc’d string No
custom_headers Array of custom headers to be sent with the email. Array [X-Custom-Header-Name]:[Value] No
X-Custom-Header-Name Each custom header key should start with X- and the header value may be a single string or an array of strings string|[strings] No
options group_name By default, transactional emails are grouped by month. By specifying this field’s name, emails will be aggregated under this group name string No
template_id Email templates can be created and stored using the Transactional Email interface. After publishing these templates, the template ID can be used to use the appropriate template on sending. string No, unless the body parameter is empty.
track_opens This field can be set to enable engagement tracking whenever a contact opens this email. Engagement reports can then be viewed on our reports interface. boolean
  • true
  • false
 No
track_links This field can be set to enable engagement tracking whenever a contact clicks any link in this email. Engagement reports can then be viewed on our reports interface. boolean
  • true
  • false
 No
unsubscribe_redirect_url Add a valid web URL to automatically redirect the user after they unsubscribe String No
attachments data Array containing the details of files attached to the email to be sent Array
  • filename
  • data
  • path
  • content_id
 No
  • filename
 Specify the name of the attached file. string Yes, if data is not empty
  • data
 The base64 encoded data of the file attachment byte Yes, if file path is empty
  • path
 The file path to the file attachment string Yes, if data is empty
  • content_id
 The content ID of an embedded image. A matching ID must be found in the HTML string No
options Array containing options for file attachments Array
  • track

No
  • track
 This field can be set to enable engagement tracking whenever a contact opens this file attachment. Engagement reports can then be viewed on our reports interface. boolean
  • true
  • false
 No

Example Requests

Example using HTML provided in the body

{
  "body": {
    "html": "<h1>Hello there, {{recipientName}}, how was the {{sports}} match?</h1>",
  "text": "Hello there, how was the match?",
  "personalisation_fields": {
    "common_fields": {"sports": "soccer" }
  },
    "unique_fields": [
        {
            "[email protected]": {"recipientName": "Mr Joe Bloggs"}
        },
        {
            "[email protected]": {"recipientName": "Johnny boy"}
        }
    ]
  },
  "options": {
    "group_name": "Track Engagement",
    "track_links": true,
    "track_opens": true
  },
  "headers": {
    "subject": "Raw HTML Template",
    "from": {
      "email": "[email protected]",
      "name": "Boss"
    },
    "to": [
      {
        "email": "[email protected]",
        "name": "Joe"
      },
    {
    "email": "[email protected]",
    "name": "John"
    }
    ],
    "cc": [
      {
        "email": "[email protected]",
        "name": "Sandy"
      }
    ],
  "reply_to": {
    "email": "[email protected]"
  }
  },
  "attachments": {
    "data": [
      {
        "filename": "Test.txt",
        "data": "V2VsbCBkb25lIQ=="
      }
    ],
  
}

Example using a template ID

curl --location 'https://api.everlytic.net/transactional/email/v1/mail' \
--header 'Content-Type: application/json' \
--data-raw '{
  "options": {
    "group_name": "Track Engagement",
    "track_links": true,
    "track_opens": true
  },
  "headers": {
    "to": [
      {
        "email": "[email protected]",
        "name": "Joe"
      },
    {
    "email": "[email protected]",
    "name": "John"
    }
    ],
    "cc": [
      {
        "email": "[email protected]",
        "name": "Sandy"
      }
    ]
  }

}'

Example Response

Status codes

Status code Explanation
200 Ok Email was sent successfully
400 Bad Request The request body was formatted improperly or the sending domain is unverified
401 Unauthorized The provided authorization credentials are incorrect
412 Precondition Failed One or more of the required fields were invalid

Properties

Properties of response with status 200 OK

Property Description Data type Parameters
transaction Array containing the IDs of each successful email Array
  • id
  • id
 The ID generated for this instance of the email string

Properties of response with 4XX status

Property Description Data type Expected parameters
code The HTTP response status code integer
  • 400
  • 401
  • 412
message The reason for the failure string Valid string
error Array containing errors field JSON
  • errors
errors Array containing the failure details JSON
  • domain
  • reason
  • message
  • locationType
  • location
domain The classification of the type of error string
  • global
  • usageLimit
  • NoQuota
reason Keyword used to describe the error string
  • invalid
  • invalidParameter
  • UnverifiedDomain
  • required
  • Attachment
  • Duplicate
  • CustomHeaders
  • NoQuota
  • Suppressed
  • RequestLimit
  • ForbiddenAccess
message Text describing the reason for the failure string Valid string
locationType The location where the failure occurred string
  • headers
  • request
  • body
location The type of validation that failed string
  • authorization
  • sendValidation
  • webhookValidation
  • suppressionValidation
  • templateValidation
  • bouncesValidation
  • trackedAttachmentsGroup
  • trackedAttachmentsAsset
  • default

Email was sent successfully [200 OK]

{
    "transactions": [
        {
            "id": "8faa62ec-6c01-4020-8322-933a8q046d9e"
        },
        {
            "id": "fe0070a5-ec15-4c99-80ae-d68707we6bc4"
        },
        {
            "id": "7e4b9585-0246-409f-b52f-e3d29g59063b"
        }
    ]
}

Sending domain is unverified [400 Bad Request]

{
    "code": 400,
    "message": "Send Failed - Unable to send: Unverified Domain - fakedomain.com",
    "error": {
        "errors": [
            {
                "domain": "global",
                "reason": "invalid",
                "message": "Send Failed - Unable to send: Unverified Domain - fakedomain.com",
                "locationType": "request",
                "location": "default"
            }
        ]
    }
}

Invalid/Missing authorization credentials [401 Unauthorized]

{
    "code": 401,
    "message": "Login Required",
    "error": {
        "errors": [
            {
                "domain": "global",
                "reason": "required",
                "message": "Login Required",
                "locationType": "request",
                "location": "authorization"
            }
        ]
    }
}

The format of the email in the from field is invalid [412 Precondition Failed]

{
    "code": 412,
    "message": {
        "errors": {
            "headers.from.email": [
                "The headers.from.email format is invalid."
            ]
        }
    },
    "error": {
        "errors": [
            {
                "domain": "global",
                "reason": "invalidParameter",
                "message": {
                    "errors": {
                        "headers.from.email": [
                            "The headers.from.email format is invalid."
                        ]
                    }
                },
                "locationType": "request",
                "location": "sendValidation"
            }
        ]
    }
}