/v1/send
Send an email
Sends one message to one or more recipients. Each recipient gets their own message. Provide a stored template (`templateSlug` or `templateId`) or raw `html` and `text`. The status is `200` when at least one recipient succeeded, `202` for a scheduled send, and `502` when every recipient failed.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
Idempotency-Key | header | No | A repeat request with the same key and API key returns the first recorded result with cached: true instead of sending again. Use one recipient per idempotent request. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
from | string | Yes | Sender address. For a non-global key, its domain must be one the key may use. |
fromName | string | No | Display name for the From header. |
to | string or string[] | Yes | One address, or up to 50. Duplicates are removed. |
replyTo | string | No | |
subject | string | No | Overrides a template's subject. Set it for raw html or text sends. |
html | string | No | HTML body. Ignored when you reference a template. |
text | string | No | Plain-text body. Ignored when you reference a template. |
templateSlug | string | No | Slug of a stored template. Preferred over templateId. Case-sensitive. |
templateId | string | No | ID of a stored template. Use templateSlug where you can. |
variables | object | No | Values for the template's placeholders. Nested objects work with dot paths. Never applied to raw html or text. |
themeId | default, ocean, forest, violet, slate | No | Colour theme for a built-in layout. Ignored for custom templates. |
listId | string | No | Audience list ID. Adds one-click unsubscribe headers. |
listUnsubscribe | string | No | Your own unsubscribe URL, passed through as the List-Unsubscribe header. |
listUnsubscribePost | boolean | No | Adds List-Unsubscribe-Post: List-Unsubscribe=One-Click. Defaults to true with listId. |
track | boolean | No | Rewrite links and add an open pixel in the HTML body. |
sendAt | string | No | ISO 8601 UTC time. More than five seconds ahead queues the message. Live keys only, and within 12 hours. |
Example
curl https://your-emailflare.workers.dev/v1/send \
-H "Authorization: Bearer eflive_xxx" \
-H "Content-Type: application/json" \
-d '{
"from": "hello@yourdomain.com",
"fromName": "Acme",
"to": "alex@example.com",
"templateSlug": "welcome",
"themeId": "ocean",
"variables": {
"name": "Alex",
"appName": "Acme"
}
}'Responses
| Status | Meaning |
|---|---|
200 | At least one recipient succeeded. Check results for per-recipient errors. A cached idempotent replay also returns 200. |
202 | The message was queued for delivery at sendAt. |
400 | A field is missing or malformed: an invalid address, more than 50 recipients, or none of templateSlug, templateId, html, text. |
401 | No bearer token, or the key is unknown or revoked. |
403 | The key's scope does not include the sender domain. |
404 | No template matches the slug or ID, or the token is unknown. |
429 | More than 100 requests in 60 seconds for this key. |
500 | Unexpected error. Check the Worker logs with wrangler tail. |
502 | Every recipient failed. The body still lists the per-recipient errors. |