Skip to content

OpenAPI 3.1

API reference.

Every public endpoint of a self-hosted EmailFlare deployment, generated from one specification. Import it into your client generator, Postman or your editor.

Server

{baseUrl}

Your workers.dev address or custom domain.

Authentication

Authorization: Bearer eflive_…

Create keys under API keys in the dashboard.

Rate limit

100 requests / 60 s

Per API key. Exceeding it returns 429.

post

/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

NameInRequiredDescription
Idempotency-KeyheaderNoA 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

FieldTypeRequiredDescription
fromstringYesSender address. For a non-global key, its domain must be one the key may use.
fromNamestringNoDisplay name for the From header.
tostring or string[]YesOne address, or up to 50. Duplicates are removed.
replyTostringNo
subjectstringNoOverrides a template's subject. Set it for raw html or text sends.
htmlstringNoHTML body. Ignored when you reference a template.
textstringNoPlain-text body. Ignored when you reference a template.
templateSlugstringNoSlug of a stored template. Preferred over templateId. Case-sensitive.
templateIdstringNoID of a stored template. Use templateSlug where you can.
variablesobjectNoValues for the template's placeholders. Nested objects work with dot paths. Never applied to raw html or text.
themeIddefault, ocean, forest, violet, slateNoColour theme for a built-in layout. Ignored for custom templates.
listIdstringNoAudience list ID. Adds one-click unsubscribe headers.
listUnsubscribestringNoYour own unsubscribe URL, passed through as the List-Unsubscribe header.
listUnsubscribePostbooleanNoAdds List-Unsubscribe-Post: List-Unsubscribe=One-Click. Defaults to true with listId.
trackbooleanNoRewrite links and add an open pixel in the HTML body.
sendAtstringNoISO 8601 UTC time. More than five seconds ahead queues the message. Live keys only, and within 12 hours.

Example

curl
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

StatusMeaning
200At least one recipient succeeded. Check results for per-recipient errors. A cached idempotent replay also returns 200.
202The message was queued for delivery at sendAt.
400A field is missing or malformed: an invalid address, more than 50 recipients, or none of templateSlug, templateId, html, text.
401No bearer token, or the key is unknown or revoked.
403The key's scope does not include the sender domain.
404No template matches the slug or ID, or the token is unknown.
429More than 100 requests in 60 seconds for this key.
500Unexpected error. Check the Worker logs with wrangler tail.
502Every recipient failed. The body still lists the per-recipient errors.
get

/v1/unsubscribe

Unsubscribe from a link

Opened from the unsubscribe link in an email. Consumes the single-use token, suppresses the address and returns a confirmation page.

Parameters

NameInRequiredDescription
tokenqueryYesThe one-time token from the unsubscribe link.

Responses

StatusMeaning
200Unsubscribed. Returns an HTML confirmation page.
400The token is missing.
404The token is invalid or already used.
post

/v1/unsubscribe

One-click unsubscribe (RFC 8058)

Mail clients post to this URL when the recipient presses unsubscribe. The token can be in the query string or a form field.

Parameters

NameInRequiredDescription
tokenqueryYesThe one-time token from the unsubscribe link.

Responses

StatusMeaning
200Unsubscribed.
400An error. Status codes: 401 missing, invalid or revoked key; 403 key not authorized for the sender domain; 404 template or token not found; 429 rate limit exceeded; 500 unexpected error.
404No template matches the slug or ID, or the token is unknown.
get

/health

Health check

Responses

StatusMeaning
200The Worker is running.