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. 

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 take many other actions.

Insider can add the transactional email events listed below to the user profiles. Each event has a subject parameter so that you can segment your users based these events, such as transactional email open, transactional email delivered, etc.

Supported transactional email events and their parameters

Transactional email events are added to the user profiles in Insider's Unified Customer Database by default for all transactional email customers. You can contact the Insider One team for further details about the configuration.

Endpoint and Headers

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

Headers

Body Parameters

The table below lists the parameters of the request body.

If the UUID is the identifier and you want to log transactional email events in the Unified Customer Database (UCD), you need to use a different parameter in the Transactional Email API payload.

• Insider has recently added the UUID parameter as a body parameter for the Transactional Email API.
• After you send the request via the Transactional Email API, the Insider Email Team will query the UCD for the profile associated with that UUID using the Profile API. Since each UUID needs to be fetched from the Profile API, the email will be sent to the recipients one by one unlike the current structure that is written under the "to" body parameter.
• If a profile with the UUID exists in the UCD, the email address ("em") of that profile will be retrieved from the UCD. The Transactional Email will be sent to that profile’s email address, and the event will be recorded in the UCD based on the UUID.
• If a profile with the given UUID does not exist in UCD, the transactional email will still be sent to the email address provided in the request. However, the event will not be recorded in UCD for that email address because no profile matching the UUID was found.
• If you are using email as an identifier, you don’t need to utilize the UUID parameter.

Webhook callbacks are generated only for requests that are successfully processed and passed to the delivery provider. Requests that are rejected or excluded as duplicates (returning 208) do not generate webhook events and will not appear in webhook logs.

*CID images append 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>
<img src=\"cid:myimagecid\"/>"
  }
],

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).

The sample request below shows a personalized HTML email with the subject "Hello", from Fashion Street to John Doe (sample@email.com), including CC and BCC recipients and dynamic fields such as first name and product name.

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@useinsider.com",
      "uuid": "1234567"
    }
  ],
  "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": "sample.cc@useinsider.com"
    }
  ],
  "bcc": [
    {
      "name": "User in BCC",
      "email": "sample.bcc@useinsider.com"
    }
  ],
  "reply_to": {
    "name": "Reply to",
    "email": "sample.reply@useinsider.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"
  }
}

Requests with Transactional Email Templates

If you create your transactional email template via the Email Template Library, you can copy the template ID to use your template it in your payload. This way, you do not need to copy the HTML of a template you create to paste it in the payload of the Transactional Email API.

If the new Email Template Library is not enabled for your account, you should create a ticket to Insider One team to activate it. Once enabled, you can use the "Copy Template ID" feature as part of the library's functionality.

To copy the ID of your transactional template, go to Templates > Transactional message type, and click the three-dot menu > Copy Template ID button.

The following is a sample payload that uses the ID of the template in the template_id key. template_id is a String and optional key.

{
  "subject": "Hello",
  "tos": [
    {
      "name": "John Doe",
      "email": "sample@useinsider.com"
    }
  ],
  "from": {
    "name": "Posh Street",
    "email": "posh@street.com"
  },
  "reply_to": {
    "name": "Reply to",
    "email": "reply@useinsider.com"
  },
  "template_id": "275",
  "content": [
    {
      "type": "text/html",
      "value": "<p>I am {{first_name}}.</p>"
    }
  ],
  "attachments": [],
  "dynamic_fields": {
    "first_name": "John",
    "last_name": "Doe",
    "product_name1": "Laptop",
    "price1": "$1000",
    "product_name2": "Iphone",
    "price2": "$850"
  }
}

• If you use the template_id within the payload, the system will fetch the template from the Email Template Library.
• If the request with the template_id parameter is sent successfully, a 200 OK response will return.
• If you use both template_id and content parameters correctly, a 200 OK response will return. The request will be sent with the template_id parameter, and it will skip the value of the content parameter.
• If you want to use only the content parameter, you need to leave the template_id parameter empty. The content parameter will be required in this case. If the request with the content parameter is sent successfully, a 200 OK response will return.
• If the template_id parameter is empty and the content parameter has no value, a 400 Bad Request response will return.
• You need to use the dynamic content with the {{name}} syntax inside the templates you create on the Email Template Library and insert the value of your dynamic content under the dynamic_fields parameter inside the payload. The dynamic fields values you want to use in transactional emails need to be inserted in the dynamic fields body parameters of the API. These values are not taken from Insider'd Unified Customer Database.

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
}

500 Internal Server Error

This response indicates that an internal error occurred on the server side and the request could not be processed.

502 Bad Gateway

This response indicates a temporary server-side or network-level issue that prevented the request from being processed.

{
  "status_message": "Temporary gateway failure. The request was not processed.",
  "timestamp": 1726944657
}

503 Service Unavailable

This response indicates that the service is temporarily unavailable due to server overload or maintenance.

504 Server Timeout

This response indicates that the server did not receive a timely response from an upstream server.

If a request with the same content is sent for the same user within 15 minutes, the system will return the following message:
"status_message": "This request has already been received and is being processed. Any duplicate content from the user will be ignored for the next 15 minutes."

520 Cloudflare Network Error

This response indicates an unexpected error on the Cloudflare network side, preventing the request from being processed.

Suggested Retry Mechanism: If any of the above errors are encountered (502, 503, 504, 520), the request was not processed successfully on the server side. A retry mechanism is recommended, distributing retries randomly within a 5-minute interval to allow server resources to recover and to prevent accidental duplicate sends

208 – Already Processed

This status code indicates that the request has already been handled, and repeating it will not trigger a new send.

{
  "message_id": "dce90e71-6786-4d69-93eb-5162a2508e15",
  "status_message": "This request has already been received and is being processed. Any duplicate content from the user will be ignored for the next 15 minutes.",
  "timestamp": 1762942657
}

This response does not indicate that the message was dropped, does not relate to suppression logic (unsubscribes, bounces, or spam complaints), or does not prevent message_id creation for valid sends; each successfully processed send still receives its own message_id.

When this response returns, you can try out the following handlings:

• Duplicate requests within 15 minutes

If the same transactional email payload is sent twice within a 15-minute deduplication window, the second request is excluded and returns a 208 response with a body such as the following:

{
  "status_message": "This request has already been received and is being processed. Any duplicate content from the user will be ignored for the next 15 minutes"
}

• Retry after temporary Gateway Failure (502 → 208)

If the initial request fails with a temporary 502 Bad Gateway, the retry may return 208. In this case:
> The first request was not queued or processed.
> The retry request was successfully accepted and queued.
> 208 indicates that the request was ultimately handled (idempotent acceptance), avoiding duplicate delivery.

• General idempotency handling (Same payload handling)

Even if two requests fail or succeed differently, 208 may be used to prevent the same payload from being processed twice. The API uses idempotency logic so that identical requests do not create multiple sends.

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.
• This API is designed exclusively for transactional use cases and must not be used for bulk or promotional emailing.
• The default rate limit is 5000 requests per second per Inone account. Higher limits can be configured on demand by contacting Insider.