Skip to content

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

200 OK
{
  "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.

POST /v1/send
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.

  1. 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.

  2. 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.

  3. Step 3

    Screen

    Each recipient is checked against your suppression list. Suppressed addresses are skipped and reported in the response.

  4. 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.

Request body fields
FieldTypeRequiredNotes
fromstringYesSender address on a domain you have set up. A key limited to certain domains can only send from those.
fromNamestringNoDisplay name shown with the sender address.
tostring or string[]YesOne address or up to 50. Each recipient gets their own message, so recipients never see each other.
replyTostringNoAddress that replies go to.
subjectstringNoRequired when you send raw html or text. With a template, it overrides the template subject.
htmlstringNo*HTML body.
textstringNo*Plain-text body.
templateSlugstringNo*Slug of a built-in or custom template. Preferred over the ID.
templateIdstringNo*Template ID, if you would rather reference that.
variablesobjectNoValues for the template. Applied to the subject and, for custom templates, the body.
themeIdstringNoColour theme for a built-in layout: default, ocean, forest, violet or slate.
listIdstringNoMarks the send as part of a list. Adds one-click unsubscribe headers and respects that list's unsubscribes.
listUnsubscribestringNoYour own unsubscribe URL, sent as the List-Unsubscribe header.
listUnsubscribePostbooleanNoAdds List-Unsubscribe-Post for RFC 8058 one-click.
trackbooleanNoOpt in to open and click tracking. Off by default.
sendAtISO 8601 stringNoDeliver later. A time in the past, or within a few seconds, sends immediately.

* Provide at least one of these four.

Headers

Request headers
HeaderValueNotes
AuthorizationBearer YOUR_KEYRequired. Live keys start with eflive_, test keys with eftest_.
Content-Typeapplication/jsonRequired.
Idempotency-Keyany stringOptional. A repeat of the same key for the same API key returns the first result instead of sending again.

Responses

Response status codes
StatusMeaning
200Processed. results has one entry per recipient, with cfId on success or error on failure. A replayed idempotency key adds cached: true.
202Scheduled. The body has scheduled: true, an id and the sendAt time.
400The payload failed validation, for example an invalid address or no template, html or text.
401The key is missing, unknown or revoked.
403The key is not allowed to send from that domain.
404The template slug or ID does not exist.
429More than 100 requests in a minute for this key.
502Every 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.

Global

Send from any domain in the workspace. Use it for your main backend.

One domain

Send only from a single domain. Good for a product or client that should not touch the others.

Several domains

Pick the exact set of domains a key may use.

Test keys

Prefixed eftest_. Nothing is delivered. The rendered message lands in the test mailbox, so you can run the real code path in CI.

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 themeId to change colours
  • Custom templates support {{name}}, nested paths like {{plan.name}}, and if, else and unless blocks
  • Missing variables render as empty text, never as {{name}}
Browse the template library
custom template body
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.

Bounce classification

Bounce reports that reach your domain are read for their status code. Hard bounces and spam rejections suppress the address at once. Soft bounces suppress it after three in 30 days.

Complaints

Spam complaint reports are matched back to the original send, marked complained in your logs, and the address is suppressed.

Suppression list

Every recipient is checked before every send. You can add addresses by hand, import a CSV and export the list.

One-click unsubscribe

Send with a listId and EmailFlare issues a token and adds List-Unsubscribe and List-Unsubscribe-Post headers, as RFC 8058 describes.

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.opened and email.clicked
  • Each webhook is signed with HMAC SHA-256 in the X-EmailFlare-Signature header
The activity log with a list of sends and the open message's envelope
Webhook payload
{
  "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!"
  }
}
Verify the signature
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 header

Playground 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
The API playground with a template picker, variable fields and a live preview of the rendered email

Limits

The numbers, plainly.

Cloudflare sets the ceiling for what your account can send. These are the limits EmailFlare adds or reports on.

Limits
LimitValueNotes
Request rate100 per minute per API keySet by the rate limiting binding in your Wrangler config, so you can change it. If the binding is absent, requests are not limited.
Recipients50 per requestSend more by making more requests.
Daily ceilingCF_DAILY_LIMIT, default 1000The 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.
SchedulingsendAt on live keysScheduled sends run through a queue. Test keys ignore sendAt and capture the message right away.

FAQ

API questions.

Replies from customers?See the team inbox

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.