Send e-mails (batch, async)

Designing

POST

/messages/email/batch/async

Enqueue more messages than the synchronous batch cap allows. Returns 202 + a jobId; poll GET /v4/jobs/{jobId} for progress and GET /v4/jobs/{jobId}/items for per-recipient outcomes. Mirrors POST /contacts/bulk/async exactly.

Still not an audience send. The caller enumerates every recipient here, same as the synchronous batch — this endpoint only lifts the 100-item cap. If you want the platform to resolve a segment for you, that is /messages/{channel}/audience.

type and basis sit on the envelope, as in the synchronous batch, and for the same reasons.

Job results are retained for a limited period (see expiresAt). Send Idempotency-Key to make retries safe: a replay returns the ORIGINAL job rather than enqueuing a second one.

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢202Accepted

application/json

Enqueued. Nothing has been sent yet — poll the job.

Headers

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠422Unprocessable Entity

🟠429Too Many Requests

🔴503Service Unavailable

Request Example

Shell

JavaScript

Java

Swift

curl --location '/messages/email/batch/async' \
--header 'Authorization: Bearer <token>' \
--header 'Idempotency-Key: 0f3e2b1a-7c4d-4e2a-9b11-2f6d8c1a5e30' \
--header 'Content-Type: application/json' \
--data '{
    "type": "transactional",
    "basis": "contract_performance",
    "messages": [
        {
            "to": {
                "contactId": "string",
                "clientContactId": "string",
                "email": "string",
                "name": "string"
            },
            "cc": [
                {
                    "email": "string",
                    "name": "string"
                }
            ],
            "bcc": [
                {
                    "email": "string",
                    "name": "string"
                }
            ],
            "from": {
                "email": "string",
                "name": "string"
            },
            "replyTo": {
                "email": "string",
                "name": "string"
            },
            "templateId": 0,
            "subject": "string",
            "htmlContent": "string",
            "textContent": "string",
            "language": "string",
            "variables": {},
            "attachments": [
                {
                    "name": "string",
                    "content": "string",
                    "url": "string"
                }
            ],
            "headers": {},
            "tracking": {
                "opens": true,
                "clicks": true
            },
            "tags": [
                "string"
            ],
            "metadata": {},
            "sendAt": "string",
            "createContact": true,
            "retainBody": true,
            "event": "string",
            "permId": "string"
        }
    ]
}'

Response Example

202 - Example 1

{
    "jobId": "string",
    "type": "string",
    "status": "string",
    "progress": {
        "total": 0,
        "processed": 0,
        "succeeded": 0,
        "failed": 0
    },
    "createdAt": "string",
    "startedAt": "string",
    "finishedAt": "string",
    "expiresAt": "string",
    "error": "string",
    "links": {
        "self": "string",
        "items": "string"
    }
}

Modified at 2026-09-07 17:58:01

Cancel scheduled message

Send SMS (batch, async)