- 22 Apr 2024
- 4 Minutes to read
Send Transactional Emails
- Updated on 22 Apr 2024
- 4 Minutes to read
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
Headers
Header | Sample Value | Description |
---|---|---|
X-INS-AUTH-KEY | 1a2b3c4d5e6f | This key is required to authorize your request. Refer to API Authentication Tokens to generate your token. |
Content-Type | application/json | This header specifies the media type of the resource. |
cache-control | no-cache | This header specifies browser caching in requests and responses. |
Body Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
subject | Subject line that is sent to the recipient | String | Yes |
tos | Email address(es) to send the email to | Array | Yes |
name | User name | String | No |
email | Email address of the recipient | String | No |
from | Email address that the email is sent from | Object | Yes |
name | Name that is used as the sender name | String | No |
email | Email address that is used as the sender email | String | No |
content | Content of the email | Array | Yes |
type | Type of your email content | String | No |
value | Email content | String | Yes |
cc | Email address(es) to send a carbon copy of the email to | Array | No |
name | User name | String | No |
email | Email address of the recipient in the cc | String | No |
bcc | Email address(es) to send a blank carbon copy of the email to | Array | No |
name | User name | String | No |
email | Email address of the recipient that is in bcc | String | No |
reply-to | Reply-to address and name that are used to send the email to | Object | No |
name | Reply-to name that the email is replied to | String | No |
email | Reply-to email that the email is replied to | String | No |
attachments | Any attachments in the email | Array | No |
content | Base64 encoded content of the attachment | String | No |
file_name | Attached file name | String | No |
dynamic_fields | Dynamic fields that you can use to personalize the content (e.g. first_name, last_name, product_name1, etc.) | Object | No |
unique_args | Unique arguments of transactional emails used for tracking purposes | Object | No |
callback | The endpoint that you define to receive the webhook events | Object | No |
url | Callback endpoint | String | No |
secret | The secret key to encrypt the body of your webhook events in SHA1 algorithm | String | No |
disposition | Comes with the value “inline” to embed CID image* | String | No |
content_id | Defined ID of the embedded image | String | No |
*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.