The API Generation step is where you create the credentials and review the request format your backend will use to call the Transactional Email API. Transactional email is sent programmatically, one message at a time, in response to events in your own system. So, instead of designing a campaign in the panel, you integrate with the Transactional Email API and send each email by making an authenticated API request.
This step contains two substeps:
Generate API Key: Generate the Transactional Email API key your backend uses to authenticate every request it sends to the Transactional Email API.
Generated Request Body: Review the example API request generated for your account, including the required headers and payload, and use it as a starting point for your integration.
Generate API key
The Generate API Key substep is where you create the Transactional Email API key that your backend uses to authenticate every request it sends to the Transactional Email API. Without a valid API key, your requests will be rejected, so this step is required before you can send any transactional emails.
API request header details
At the top of the Generate API Key substep, you will see an informative accordion component. When collapsed, it shows a summary label indicating it contains details about the API key. When expanded, it displays:
A description explaining why you need an API key for transactional email.
The API Request Header Details section listing the dynamic header values configured for your account (e.g., the authentication key placeholder and other required header contents) that you will use in your API request.
Review this section carefully before generating the key, as the header values shown are specific to your account's configuration. The API requires three headers on every request:
Header | Value |
|---|---|
X-INS-AUTH-KEY | Your generated Transactional Email API key |
Content-Type | application/json |
Cache-Control | no-cache |
Generate your API key
Below the informative accordion, click the Generate API Key button to open the API Key generation drawer. The drawer follows the same two-step flow used in Settings > InOne Settings > Integration Settings > API Keys.
Step 1: IP Address Authorization
In the first step, you will authorize the IP addresses allowed to call the Transactional Email API using this key. You choose one of the following options:
Click Add My IP to automatically authorize your current IP address.
Manually enter trusted IP addresses one by one.
Choose Authorize All IP Addresses to allow requests from any IP.
If an IP address cannot be authorized, the existing error state is shown, and you can adjust the entry.
Step 2: API Key
In the second step, your API key is generated and presented. You can copy the generated API key using the copy action.
If you attempt to close the drawer without copying the API key, you will be prompted with the "Leave and Discard API Key?" confirmation to prevent accidental loss of the key.
After you click the Done button, the informative accordion at the top of the substep resets to its collapsed state, regardless of whether it was expanded before the drawer was opened.
Once an API key has been successfully generated at least once, you can proceed to the next step.
After the key is generated, the button label changes to Generate Transactional Email API Key Again. Below the button, you will see who generated the key and when.
Clicking Generate Transactional Email API Key Again opens the same drawer, allowing you to create a new key. Keep in mind that generating a new key does not automatically revoke the old one. You can manage keys through Settings > InOne Settings > Integration Settings > API Keys if you need to revoke a previous key.
Only users with the Admin role can click the Generate API Key button. Non-admin users see an informational message explaining that only admin users can create an API key, and the button is not clickable.
Generated Request Body
The Generated Request Body substep shows the example API request generated for your account. You can use the generated API request as is or customize it to meet your business needs when sending transactional emails.
The endpoint for sending transactional emails is POST https://mail.useinsider.com/mail/v1/send.
Details about the API request
At the top of the substep, a collapsible accordion titled Details About API Request is displayed (collapsed by default). When expanded, it shows a detailed guide about the fields and parameters in the API request payload, presented as a table.
The payload fields include the following:
Field | Type | Required | Description |
|---|---|---|---|
subject | String | Yes | The subject line of the transactional email |
tos | Array | Yes | List of recipient objects. Each recipient object includes name, email, and optionally uuid for identification. |
from | Object | Yes | The sender identity for the email. Contains name and email. Pre-filled with the default sender address configured in Sender Address Setup. |
content | Array | Yes | List of content objects defining the email body. Each object contains type (e.g., text/html) and value (the content, which can include dynamic field placeholders such as {{first_name}}). |
template_id | String | No | Identifier of a ready-made Transactional Email template to use instead of inline content. When provided, the template body is used and you can populate its placeholders through dynamic_fields. |
cc | Array | No | List of recipient objects to copy on the email. |
bcc | Array | No | List of recipient objects to blind-copy on the email. |
reply_to | Object | No | The reply-to identity for the email, containing name and email. |
dynamic_fields | Object | No | Key-value pairs used to personalize the email content. Keys referenced in content.value (for example, {{first_name}}) are replaced with the corresponding values at send time. |
unique_args | Object | No | Custom key-value arguments attached to the email for tracking and segmentation in your transactional email analytics. |
attachments | Array | No | List of attachment objects. Each attachment contains content (Base64-encoded file content) and file_name. To embed an image inline in the HTML body (for example, referenced as <img src="cid:my-image">), also set disposition to "inline" and content_id to the CID referenced in the HTML. |
callback | Object | No | Optional callback configuration containing url and secret, used to receive delivery and engagement events for this email. |
The Transactional Email API supports up to 5,000 requests per second. If your backend needs higher throughput, contact the Insider One team.
Example API Request
Below the accordion, the Example API Request section shows a complete example curl command. The header values shown reflect the dynamic configuration of your account; the from section is pre-filled with your default sender address.
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: {YOUR_API_KEY}' \
--data-raw '{
"subject": "Hello",
"tos": [
{
"name": "John Doe",
"email": "sample@useinsider.com",
"uuid": "1234567"
}
],
"from": {
"name": "{YOUR_DEFAULT_SENDER_NAME}",
"email": "{YOUR_DEFAULT_SENDER_EMAIL}"
},
"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"
},
"unique_args": {
"category": "Confirmation Email",
"purchase_channel": "App"
},
"attachments": [
{
"content": "aW5zaWRlciB0ZXN0",
"file_name": "file.txt"
}
],
"callback": {
"url": "yourcallbackurl",
"secret": "yoursecret"
}
}'Below the code snippet, you will see two actions:
Export: Download the example request as a file to share with your team.
Copy: Copy the example request to your clipboard.
API request guide and customization tips
Below the code snippet area, you can learn how to send API requests, including standards for request body parameters, limitations, and more.
This section contains six collapsible accordions, each collapsed by default:
How to use ready-made templates for Transactional Email content?
How to use dynamic fields for personalized Transactional Emails?
How can I send my API Request through Postman?
How to handle error codes?
How to use the API Request to send Transactional Emails?
Learn about the API request limitations
Each accordion expands to show descriptive content guiding you on the respective topic.
For the complete, authoritative API reference, including the full list of response codes (e.g., 202, 400, 401, 500, 503, 504, 208, 520) and the transactional email event types (txn_email_delivered, txn_email_open, txn_email_click, txn_email_bounce, txn_email_spam, txn_email_unsubscribe) that you can consume via the callback URL, refer to Transactional Email API.