> ## Documentation Index
> Fetch the complete documentation index at: https://developer.effilink.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Batch Transactional Email Send — Up to 100 Versions
> Send up to 100 individually personalized transactional emails in one API request, each with its own recipients, content, and parameters.
## Overview
Send up to **100 personalized email versions** in a single API call using the `messageVersions` array. Each version can target up to 20 recipients and independently override the top-level subject, content, template, and personalization parameters. This is the most efficient way to dispatch a batch of individually tailored transactional messages without making one request per recipient.
This uses the same endpoint as [single transactional sends](/api/transactional-send), with the addition of the `messageVersions` field.
**Base URL:** `https://api.effilink.co`
**Endpoint:** `POST /v5/transactional/mail/sends_customised`
**Authentication:** `ApiKey` header
***
## Content Priority Order
When multiple content sources are provided, the following priority applies (highest to lowest):
1. `messageVersions[].templateName`
2. `messageVersions[].content`
3. Top-level `templateName`
4. Top-level `content`
***
## Request Parameters
All [single send parameters](/api/transactional-send#request-parameters) are supported at the top level and serve as defaults across all versions. The `messageVersions` array is required for batch sends.
Default email subject line, used for any version that does not define its own `subject`.
Default HTML email body content. Used for versions that do not specify `content` or `templateName`. Required if no top-level `templateName` is set and no version provides its own content source.
Default saved template name. Used for versions that do not specify their own `templateName` or `content`.
Default key-value personalization tags applied to all versions. Version-level `params` override these values when the same key is present.
```json theme={null}
{ "brand": "Your Store", "supportEmail": "help@yourdomain.com" }
```
Verified sender email address. Applies to all versions.
Sender display name. Maximum **200 bytes**. Applies to all versions.
Reply-to email address. Applies to all versions.
Scheduled send time in ISO 8601 UTC format (e.g. `2024-03-10T12:00:00Z`). Up to **72 hours** in advance. Omit to send immediately.
Set to `1` to enable open tracking across all versions.
Set to `1` to enable click tracking across all versions.
Email category label. Maximum **100 bytes**, alphanumeric only.
Campaign name for analytics grouping. Maximum **100 bytes**, alphanumeric only.
A unique message identifier for tracking and deduplication purposes. Maximum **50 bytes**.
A single file to attach to all emails in the batch. Only one attachment is supported per request.
The filename of the attachment, including its extension (e.g. `invoice.pdf`).
Base64-encoded content of the file to attach.
Set to `true` to validate and process the request without delivering any emails.
Array of up to **100** individual email versions. Each version inherits top-level values and may override them selectively.
List of primary recipients for this version. Maximum **20** recipients.
Each item: `{ "email": "string (required)", "name": "string (optional)" }`
List of CC recipients for this version. Maximum **20** recipients.
Each item: `{ "email": "string (required)", "name": "string (optional)" }`
List of BCC recipients for this version. Maximum **20** recipients.
Each item: `{ "email": "string (required)", "name": "string (optional)" }`
Version-level subject line. Overrides the top-level `subject` for this version only.
Version-level HTML email body. Overrides the top-level `content` for this version (unless a version-level `templateName` is also set).
Version-level template name. Takes highest priority — overrides both version-level `content` and all top-level content sources.
Version-level personalization tags. These override any matching keys from the top-level `params` for this version only.
```json theme={null}
{ "name": "Alice", "orderId": "ORD-001", "status": "Shipped" }
```
***
## Response Fields
`200` on success. See the [error codes table](#error-codes) for failure values.
Empty string (`""`) on success. Contains an error description on failure.
***
## Error Codes
| Code | Cause |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Missing required parameter; `messageVersions` exceeds 100 entries; a version's `to`, `cc`, or `bcc` array exceeds 20 recipients; invalid `sendDate` format; `category`, `campaign`, or `uniqueMsgID` too long; invalid recipient address; sender name too long; invalid reply-to address; missing content |
| `403` | Sender address not registered; template not found; insufficient account credits |
***
## Example
### Request
```bash theme={null}
curl --request POST \
--url https://api.effilink.co/v5/transactional/mail/sends_customised \
--header 'Content-Type: application/json' \
--header 'ApiKey: YOUR_API_KEY' \
--data '{
"subject": "Order update for {{orderId}}",
"content": "Hello {{name}},
Your order {{orderId}} status: {{status}}
",
"senderMail": "noreply@yourdomain.com",
"trackOpen": 1,
"messageVersions": [
{
"to": [{"email": "alice@example.com", "name": "Alice"}],
"params": {"name": "Alice", "orderId": "ORD-001", "status": "Shipped"}
},
{
"to": [{"email": "bob@example.com", "name": "Bob"}],
"params": {"name": "Bob", "orderId": "ORD-002", "status": "Processing"}
}
]
}'
```
### Response
```json theme={null}
{
"code": 200,
"message": ""
}
```