Email API
Send with one request.
POST to /v1/send from any language. Templates, scoped keys, bounce handling and logs come with it, and every message leaves through your own Cloudflare account.
POST /v1/send
One endpoint, any language.
Authenticate with a Bearer key, name a template and pass variables. Or send raw HTML or text. Replace the host with your own Worker's URL.
What comes back
{
"results": [
{
"to": "alex@example.com",
"cfId": "b6c1e0f2-5a8e-4d1e-9c35-2f7a1d0e4a11"
}
]
}cfId is the Cloudflare message ID. It is also what you search for in the activity logs.
curl -X POST https://your-emailflare.workers.dev/v1/send \
-H "Authorization: Bearer eflive_your_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: welcome-alex-1" \
-d '{
"from": "hello@yourdomain.com",
"fromName": "Acme",
"to": "alex@example.com",
"templateSlug": "welcome",
"variables": {
"name": "Alex",
"appName": "Acme",
"loginUrl": "https://app.acme.dev/login"
}
}'Inside a request
What happens between your POST and the inbox.
Four steps, all inside your Worker. Nothing is forwarded to a third-party sending service.
Step 1
Authenticate
The Bearer key is hashed and looked up. Revoked keys are rejected, and each key is limited to 100 requests a minute.
Step 2
Prepare
Your template is found by slug or ID and rendered with your variables. The key's domain scope is checked against the sender.
Step 3
Screen
Each recipient is checked against your suppression list. Suppressed addresses are skipped and reported in the response.
Step 4
Deliver and log
The message goes out through Cloudflare, with unsubscribe headers when you ask for them. The result is logged with its message ID.
Reference
Request fields.
Send JSON. Unknown fields are ignored. At least one of templateSlug, templateId, html or text is required.
| Field | Type | Required | Notes |
|---|---|---|---|
| from | string | Yes | Sender address on a domain you have set up. A key limited to certain domains can only send from those. |
| fromName | string | No | Display name shown with the sender address. |
| to | string or string[] | Yes | One address or up to 50. Each recipient gets their own message, so recipients never see each other. |
| replyTo | string | No | Address that replies go to. |
| subject | string | No | Required when you send raw html or text. With a template, it overrides the template subject. |
| html | string | No* | HTML body. |
| text | string | No* | Plain-text body. |
| templateSlug | string | No* | Slug of a built-in or custom template. Preferred over the ID. |
| templateId | string | No* | Template ID, if you would rather reference that. |
| variables | object | No | Values for the template. Applied to the subject and, for custom templates, the body. |
| themeId | string | No | Colour theme for a built-in layout: default, ocean, forest, violet or slate. |
| listId | string | No | Marks the send as part of a list. Adds one-click unsubscribe headers and respects that list's unsubscribes. |
| listUnsubscribe | string | No | Your own unsubscribe URL, sent as the List-Unsubscribe header. |
| listUnsubscribePost | boolean | No | Adds List-Unsubscribe-Post for RFC 8058 one-click. |
| track | boolean | No | Opt in to open and click tracking. Off by default. |
| sendAt | ISO 8601 string | No | Deliver later. A time in the past, or within a few seconds, sends immediately. |
* Provide at least one of these four.
Headers
| Header | Value | Notes |
|---|---|---|
| Authorization | Bearer YOUR_KEY | Required. Live keys start with eflive_, test keys with eftest_. |
| Content-Type | application/json | Required. |
| Idempotency-Key | any string | Optional. A repeat of the same key for the same API key returns the first result instead of sending again. |
Responses
| Status | Meaning |
|---|---|
| 200 | Processed. results has one entry per recipient, with cfId on success or error on failure. A replayed idempotency key adds cached: true. |
| 202 | Scheduled. The body has scheduled: true, an id and the sendAt time. |
| 400 | The payload failed validation, for example an invalid address or no template, html or text. |
| 401 | The key is missing, unknown or revoked. |
| 403 | The key is not allowed to send from that domain. |
| 404 | The template slug or ID does not exist. |
| 429 | More than 100 requests in a minute for this key. |
| 502 | Every recipient failed. Read results for the reason per address. |
Full guides live in the docs, starting with send an email.
API keys
Give each service the access it needs.
Administrators create keys in the dashboard. The full key is shown once, only its hash is stored, and you can revoke it at any time.
Templates and variables
Keep the email out of your code.
Send by slug and pass variables. Use one of the built-in layouts, or write your own with variables and conditionals.
- Built-in layouts take a
themeIdto change colours - Custom templates support
{{name}}, nested paths like{{plan.name}}, andif,elseandunlessblocks - Missing variables render as empty text, never as
{{name}}
Hi {{name}},
{{#if trialDays}}
Your trial ends in {{trialDays}} days.
{{else}}
Thanks for being a customer.
{{/if}}
{{plan.name}} plan, renewing {{plan.renewsOn}}.Deliverability
Protect your sender reputation by default.
Bounces and complaints arrive through Cloudflare Email Routing, so the same Worker that sends your mail also listens for what went wrong.
Logs and webhooks
Know what happened to every message.
Each send is a log row with its status, error and Cloudflare message ID. Search by recipient, sender or subject, and filter to failures.
- Statuses: pending, sent, failed, bounced and complained
- Open a message to see its envelope, metadata and raw event JSON
- Webhooks fire on
email.sent,email.failed,email.openedandemail.clicked - Each webhook is signed with HMAC SHA-256 in the
X-EmailFlare-Signatureheader

{
"id": "Zk3p0...",
"event": "email.sent",
"created_at": "2026-11-21T09:18:19.000Z",
"data": {
"id": "Qm8c1...",
"to": "alex@example.com",
"from": "hello@yourdomain.com",
"subject": "Welcome to Acme, Alex!"
}
}import { createHmac, timingSafeEqual } from "node:crypto";
export function isValid(rawBody: string, signature: string, secret: string) {
const expected = createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signature);
return a.length === b.length && timingSafeEqual(a, b);
}
// signature: the X-EmailFlare-Signature headerPlayground and test mailbox
Try a send before you write any code.
Pick a template and a theme, fill in the variables and see the rendered email. Send it to the sandbox, or to a real address when you are ready.
- Test sandbox mode needs no API key
- Generates client code for the request you built
- Test mail appears in the test mailbox, never in a real inbox

Limits
The numbers, plainly.
Cloudflare sets the ceiling for what your account can send. These are the limits EmailFlare adds or reports on.
| Limit | Value | Notes |
|---|---|---|
| Request rate | 100 per minute per API key | Set by the rate limiting binding in your Wrangler config, so you can change it. If the binding is absent, requests are not limited. |
| Recipients | 50 per request | Send more by making more requests. |
| Daily ceiling | CF_DAILY_LIMIT, default 1000 | The figure the overview compares your sends against. Set it to match your Cloudflare plan. EmailFlare does not enforce it, and Cloudflare applies the limits of your plan. |
| Scheduling | sendAt on live keys | Scheduled sends run through a queue. Test keys ignore sendAt and capture the message right away. |
Send your first email from your own account.
Deploy EmailFlare, add a domain, create a key and call /v1/send. Your mail never leaves your Cloudflare account.

