Send an email
The POST /v1/send reference. Request fields, examples, responses, scheduling, tracking and errors.
On this page
POST /v1/send sends one message to one or more recipients. You can send a stored template or raw html and text.
POST /v1/send
Authorization: Bearer eflive_xxxxxxxxxxxxxxxx
Content-Type: application/json
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, for example Acme. |
to |
string or string[] | Yes | One address, or up to 50. Duplicates are removed. Each recipient gets their own message, so nobody sees the others. |
replyTo |
string | No | Address that replies go to. |
subject |
string | See note | Subject line. Overrides a template’s subject. Set it for raw html or text sends. |
html |
string | See note | HTML body. Ignored when you reference a template. |
text |
string | See note | Plain-text body. Ignored when you reference a template. |
templateSlug |
string | See note | Slug of a stored template. Preferred over templateId. |
templateId |
string | See note | ID of a stored template. |
variables |
object | No | Values for the template’s placeholders. Nested objects work with dot paths. Applied to templates only, never to raw html or text. |
themeId |
string | No | Colour theme for a built-in layout: default, ocean, forest, violet or slate. Ignored for custom templates. |
listId |
string | No | Audience list ID. Adds one-click unsubscribe headers. See Unsubscribe and suppressions. |
listUnsubscribe |
string | No | Your own unsubscribe URL, passed through as the List-Unsubscribe header. Used when listId is not set, or when the deployment has no PUBLIC_URL. |
listUnsubscribePost |
boolean | No | Adds List-Unsubscribe-Post: List-Unsubscribe=One-Click. Defaults to true with listId. Set it to true yourself when you pass listUnsubscribe. |
track |
boolean | No | Rewrite links and add an open pixel. Off unless you set it. See Track opens and clicks. |
sendAt |
string | No | ISO 8601 UTC time to deliver, for example 2026-03-01T09:00:00Z. See Schedule a send. |
A request must include at least one of templateSlug, templateId, html or text. Otherwise it fails validation.
A request header,
Idempotency-Key, is also supported. See Retry safely.
Examples
curl
curl -X POST 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" }
}'
JavaScript
const res = await fetch("https://your-emailflare.workers.dev/v1/send", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.EMAILFLARE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: "hello@yourdomain.com",
to: "alex@example.com",
subject: "Your receipt",
html: "<p>Thanks for your order.</p>",
text: "Thanks for your order.",
}),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error ?? `Send failed with ${res.status}`);
Python
import os
import requests
res = requests.post(
"https://your-emailflare.workers.dev/v1/send",
headers={"Authorization": f"Bearer {os.environ['EMAILFLARE_API_KEY']}"},
json={
"from": "hello@yourdomain.com",
"to": ["alex@example.com", "sam@example.com"],
"templateSlug": "magic-link",
"variables": {"name": "Alex", "appName": "Acme", "magicUrl": "https://acme.com/login?t=abc"},
},
timeout=10,
)
res.raise_for_status()
print(res.json()["results"])
Responses
Sent
{
"results": [
{ "to": "alex@example.com", "cfId": "cf_msg_xxxxxxxxxxxx" },
{ "to": "sam@example.com", "error": "Suppressed: hard_bounce" }
]
}
cfId is the message ID from Cloudflare Email Sending. For a test key it is a generated ID. Each recipient has its own entry, with either a cfId or an error.
The status is 200 when at least one recipient succeeded. If every recipient failed, it is 502, and the body still lists the per-recipient errors. Check the results array, not only the status code.
A recipient can fail because the address is suppressed, or because Cloudflare rejected the message.
Errors
| Status | Body | Cause |
|---|---|---|
400 |
Validation issues | A field is missing or malformed: an invalid address, more than 50 recipients, or none of templateSlug, templateId, html, text. |
401 |
Missing API key or Invalid or revoked API key |
No bearer token, or the key is unknown or revoked. |
403 |
API key not authorized for this domain |
The key’s scope does not include the sender domain. |
404 |
Template not found |
No template matches templateSlug or templateId. Slugs are case-sensitive. |
429 |
Rate limit exceeded |
More than 100 requests in 60 seconds for this key. |
502 |
results with an error per recipient |
Every recipient failed. |
500 |
Internal server error |
Unexpected error. Check the Worker logs with wrangler tail. |
Limits
- Up to 50 recipients per request.
- The API has no attachment,
ccorbccfield. - Sends are logged with the template, key and Cloudflare message ID. Search them under Activity logs.
Schedule a send
Set sendAt to a time more than five seconds in the future and the API queues the message instead of sending it.
{
"from": "hello@yourdomain.com",
"to": "alex@example.com",
"subject": "Your trial ends tomorrow",
"html": "<p>Your trial ends tomorrow.</p>",
"sendAt": "2026-03-01T09:00:00Z"
}
The response is 202:
{ "scheduled": true, "id": "…", "sendAt": "2026-03-01T09:00:00.000Z" }
Things to know:
- Use a UTC timestamp ending in
Z. - Scheduling works with live keys. A test key sends immediately.
- Scheduled messages are delivered from the fields you submitted:
from,fromName,to,subject,html,textandreplyTo. Templates, variables and unsubscribe headers are not applied at delivery time, so render the message first and send the finalhtml. - Delivery uses a queue message delay. Cloudflare Queues limit a delay to 12 hours, so schedule within the next 12 hours.
- A successful delivery fires an
email.sentwebhook.
Track opens and clicks
Set track: true and EmailFlare rewrites every http and https link in the HTML body to pass through /v1/t/c/<token>, and adds a one-pixel image served from /v1/t/o/<token>. Tracking applies to the HTML body only.
Opens and clicks fire the email.opened and email.clicked webhooks. The links use your deployment’s PUBLIC_URL, so set it to your public origin first. Image proxies and mail clients that preload images inflate open counts, so treat opens as a rough signal.
Retry safely
Send an Idempotency-Key header and EmailFlare returns the earlier result instead of sending again.
curl -X POST https://your-emailflare.workers.dev/v1/send \
-H "Authorization: Bearer eflive_xxx" \
-H "Idempotency-Key: order-1042-receipt" \
-H "Content-Type: application/json" \
-d '{ "from": "hello@yourdomain.com", "to": "alex@example.com", "templateSlug": "order-confirm", "variables": { "orderId": "1042" } }'
A repeat request with the same key and the same API key returns 200 with cached: true and the first recorded result. Use one recipient per idempotent request, because the cached response lists a single result.