Send Transactional Emails

The domains from which you send transactional emails must be authorized. If you have any questions regarding domain authorization, or want to authenticate more domains, you can create a ticket to Insider's Operational Excellence Team for your query to be redirected to Insider's deliverability team. If you try to send your transactional emails from an unauthorized domain, you will receive an error message and your emails cannot be sent. 

Overview

This API enables you to send targeted ecommerce and personalized one to one emails to your users. You can trigger these emails once a user takes a specific action on your platform.

You can use transactional emails to:

• Send a post-purchase email to share details about a purchase/booking,
• Help your users reset their password if they forget it,
• Confirm an order a user places,
• Share delivery tracking details of a purchase (when it is shipped, on the way, and delivered) and to take many other actions.

Endpoint and Headers

POST https://mail.useinsider.com/mail/v1/send

Headers

Body Parameters

*CID images function by appending the image to the email you transmit. Subsequently, standard HTML image tags are employed, directing to the image and embedding it in the email when the recipient opens it. To embed the image into your transactional email, follow these steps:

1. Attach the image to the transactional email using the following configuration:

"attachments": [
  {
    "disposition": "inline",
    "file_name": "image.jpg",
    "contentType": "image/jpeg",
    "content_id": "myimagecid",
    "content": "your_image_encoded_in_base64_goes_here_as_a_string"
  }
],

2. Embed the image into your transactional email with the following configuration:

"content": [
  {
    "type": "text/html",
    "value": "<p>Embedded image:</p><br><img src=\"cid:myimagecid\"/>"
  }
],

Sample Example

Sample Request

Every request made to the request endpoint requires a request body formatted in JSON and containing your email's content and metadata (e.g. to, reply-to, and email subject).

curl --location --request POST 'https://mail.useinsider.com/mail/v1/send' \
--header 'Content-Type: application/json' \
--header 'Cache-Control: no-cache' \
--header 'X-INS-AUTH-KEY: 1a2b3c4e5d6f' \
--header 'Cookie: __cfduid=d1a0bc0c8335c7fecbd3485839787329b1615112066' \
--data-raw '{
  "subject": "Hello",
  "tos": [
    {
      "name": "John Doe",
      "email": "sample@mail.com"
    }
  ],
  "from": {
    "name": "Posh Street",
    "email": "posh@street.com"
  },
  "content": [
    {
      "type": "text/html",
      "value": "<p>I am {{first_name}}.</p>"
    }
  ],
  "cc": [
    {
      "name": "User in CC",
      "email": "user.cc@mail.com"
    }
  ],
  "bcc": [
    {
      "name": "User in BCC",
      "email": "user.bcc@mail.com"
    }
  ],
  "reply_to": {
    "name": "Reply to",
    "email": "reply@mail.com"
  },
  "dynamic_fields": {
    "first_name": "John",
    "last_name": "Doe",
    "product_name1": "Laptop",
    "price1": "$1000",
    "product_name2": "Iphone",
    "price2": "$850"
  },
  "unique_args": {
    "category": "Confirmation Email",
    "purchase_channel": "App"
  },
  "attachments": [
    {
      "content": "aW5zaWRlciB0ZXN0",
      "file_name": "file.txt"
    }
  ],
  "callback": {
    "url": "yourcallbackurl",
    "secret": "yoursecret"
  }
}'

Sample Responses

202 Accepted

This response indicates that your request was successfully completed.

{
    "message_id": "8e664ecd-352d-4dbd-9786-ceb78b5b173b",
    "status_message": "accepted"
}

400 Bad Request

This response indicates that your request is missing the email address in the 'to' parameter.

{
  "errors": [
    "Missing 'email' on 'tos' parameter"
  ],
  "status_message": "failed to validate request"
}

400 Bad Request

This response indicates that the request has an invalid callback URL.

{
  "errors": [
    "Invalid callback URL in 'url' on 'callback'"
  ],
  "status_message": "failed to validate request"
}

400 Missing Content Type

This response indicates that the content type header of the request is incorrect.

{
  "message": "content type must be application/json",
  "status": 400
}

400 Missing Subject Line

This response indicates that the request is missing the 'subject' parameter.

{
  "errors": [
    "Missing 'subject' parameter"
  ],
  "message": "bad-request",
  "status": 400
}

400 Missing Content

This response indicates that the request is missing the 'content' parameter.

{
  "errors": [
    "Missing 'content' parameter"
  ],
  "message": "bad-request",
  "status": 400
}

400 Missing 'from' Parameter

This response indicates that the request is missing the 'from' parameter.

{
  "errors": [
    "Missing 'from' parameter"
  ],
  "message": "bad-request",
  "status": 400
}

400 Missing 'to' Parameter

This response indicates that the request is missing the 'to' parameter.

{
  "errors": [
    "Missing 'to' parameter"
  ],
  "message": "bad-request",
  "status": 400
}

401 Invalid API Key

This response indicates that the API key provided in the request is invalid, expired, or revoked.

{
  "message": "The provided API key is invalid, expired or revoked",
  "status": 401
}

401 Unauthenticated Domain

This response indicates that your domain is not authenticated.

{
  "message": "The domain you are trying to use is not authenticated. Please create a support ticket for the Insider Support Team to authenticate it.",
  "status": 401
}

Limitations

• All functions must be executed with a simple HTTPS POST request.
• Only new emails can be sent via this API. No data can be retrieved.
• The API Key should be provided as the authorization key on the request header. If the key is incorrect, the operation will not be executed and an authorization error will return in the response.
• Transactional API cannot be used for sending bulk emails. It is designed only to set transactional emails.
• The rate limit is 2000 requests per second.