How does a Cloudflare Worker send order confirmations through Email Service's send_email binding, and what do its restrictions and plan limits change?
answer
- binding, then env.EMAIL.send()
- resolves to a messageId
- errors carry an E_ code
- onboarded sending domain, Workers Paid
- allowed_sender_addresses narrows the binding
basics
~20 sDeclare a send_email binding and call env.EMAIL.send() with from, to, subject and html or text; it resolves to a messageId. Mailing customers needs an onboarded sending domain and the Workers Paid plan; verified destination addresses are free on every plan.
solid answer
~40 sA `send_email` entry in the Wrangler file, such as `{ "name": "EMAIL" }`, puts a `SendEmail` binding on `env`. `env.EMAIL.send()` takes a builder object (`from`, `to`, `subject`, `html` and/or `text`, optional `cc`, `bcc`, `replyTo`, `attachments`, `headers`) and resolves to `{ messageId }`. On failure it throws an error whose `code` names the cause, such as `E_SENDER_NOT_VERIFIED`, `E_RATE_LIMIT_EXCEEDED` or `E_DAILY_LIMIT_EXCEEDED`. The `from` address must be on a domain onboarded to Email Service. Until a **sending domain** is onboarded, mail can go only to verified destination addresses, which is also the only option on Workers Free. Sending to customers needs the Workers Paid plan: 3,000 emails a month are included, then $0.35 per 1,000. The `destination_address`, `allowed_destination_addresses` and `allowed_sender_addresses` attributes narrow what one binding may do.
code
json · 9 lines{
"name": "order-mail",
"main": "src/index.js",
"compatibility_date": "2026-10-01",
"send_email": [
{ "name": "EMAIL", "allowed_sender_addresses": ["[email protected]"] },
{ "name": "NOTIFY_OPS", "destination_address": "[email protected]" }
]
}go deeper
Recall the send_email binding, the env.EMAIL.send() fields and that it resolves to a messageId.
Explain who may receive mail before and after a sending domain is onboarded, what each restriction attribute does, the error codes worth handling, and the size and recipient limits.
Show the production habits: restricted bindings, retrying rate and daily limit errors from a queue, handling suppressed recipients, and tracking delivery through sending logs or events rather than the routing summary.
Weigh a beta, transactional-only service with a growing daily quota against the mail a product must send, and who owns sender reputation and the suppression list.
## The binding and the call Cloudflare **Email Service** has two halves: Email Routing receives mail, and **Email Sending** sends it. Email Sending has been in public beta since 2026-04-16 and can be reached three ways: the REST API, authenticated SMTP, and, from a Worker, the `send_email` binding. The binding needs no API token, because the Worker's configuration grants it. Code outside Workers sends the same mail with an API token, through the REST API's `/accounts/{account_id}/email/sending/send` endpoint or over SMTP on `smtp.mx.cloudflare.net:465`, and all three paths share one delivery pipeline and one set of limits. Declare the binding in the Wrangler file: - `"send_email": [{ "name": "EMAIL" }]` gives the Worker `env.EMAIL`; - `send_email` is not inherited by Wrangler environments, so repeat it in each one. Call `env.EMAIL.send(builder)`. The builder holds: - `from`, a string or `{ email, name }`, which must be on a domain onboarded to Email Service; - `to`, `cc`, `bcc`, each a string, an `{ email, name }` object, or an array of either; - `subject`, plus `html` and/or `text`; - optional `replyTo`, `attachments` (`content`, `filename`, `type`, `disposition`) and `headers`. The promise resolves to an `EmailSendResult`, `{ messageId }`. The binding also accepts the older form, an `EmailMessage` from `cloudflare:email` wrapping raw MIME. The docs keep that form for code that already builds MIME and recommend the builder for new code. ## Who may receive the mail | Situation | Who can receive it | |---|---| | Workers Free, or Paid with no sending domain onboarded | only verified destination addresses in the account | | Workers Paid with an onboarded sending domain | any recipient | Sends to **verified destination addresses** are free on every plan and do not count toward any quota. That makes them useful for alerts to your own team. Order confirmations go to customers, so they need the Workers Paid plan and an onboarded **sending domain**. Onboarding adds MX, SPF and DKIM records on the `cf-bounce` subdomain, and Email Service signs outgoing mail for you. A new account starts with a conservative **daily quota** that grows with its sending reputation. Email Service is meant for **transactional** mail only, such as receipts, password resets and notifications. It is not for marketing campaigns. ## Restricting a binding Each `send_email` entry can be narrowed, which limits the damage a bug or a compromised dependency can do: | Attribute | Effect | |---|---| | none | may send to any verified destination address, or to anyone once a sending domain is onboarded | | `destination_address` | may send only to that one address; `to` may then be left out | | `allowed_destination_addresses` | may send only to the listed addresses | | `allowed_sender_addresses` | may send only from the listed addresses | A shop gives its order Worker one binding restricted to `orders@` as sender, and a second binding fixed to the operations inbox for alerts. ## Errors to handle `send()` throws a standard `Error` with a `code` property. The ones an order flow meets most: - `E_SENDER_NOT_VERIFIED` or `E_SENDER_DOMAIN_NOT_AVAILABLE`: the `from` domain is not verified or not onboarded; - `E_RECIPIENT_NOT_ALLOWED`: the recipient is outside `allowed_destination_addresses`; - `E_RECIPIENT_SUPPRESSED`: a recipient is on the suppression list while **Drop suppressed recipients** is off, its default; - `E_RATE_LIMIT_EXCEEDED` and `E_DAILY_LIMIT_EXCEEDED`: retry later, ideally from a queue; - `E_TOO_MANY_RECIPIENTS`, `E_TOO_MANY_ATTACHMENTS`, `E_CONTENT_TOO_LARGE`: the message breaks a size limit. Treat the two limit errors, and `E_INTERNAL_SERVER_ERROR`, as retryable. Most other codes point at configuration or data to fix, and retrying them only repeats the failure. ## Limits and pricing - **50** recipients per email across `to`, `cc` and `bcc`. - **5 MiB** total message size including attachments, or 25 MiB to verified destination addresses. - **32** attachments, **16 KB** of custom headers, and a subject of up to **998** characters. - Workers Paid includes **3,000** emails per account per month, then **$0.35 per 1,000**. A hard bounce still counts, while a send refused at the API, such as a suppressed one, does not. ## Knowing it was delivered A resolved `send()` means Email Service **accepted** the message, not that the customer's server did. Delivery shows in the Email Sending logs and metrics (*Delivered*, *Delivery failed*), and in event subscriptions such as `message.delivered` and `message.bounced` delivered to a queue. Do not read the Email Routing summary for this: it lists mail sent from a Worker as dropped even when it was delivered.
- Why restrict a send_email binding with allowed_sender_addresses?It caps what the Worker can do even when its code is wrong or a dependency misbehaves. The binding may send only from the listed addresses, such as `orders@`, so a bug cannot send mail as `ceo@`. `allowed_destination_addresses` and `destination_address` cap recipients the same way, which suits alert bindings.
- What happens when an order confirmation is addressed to a suppressed recipient?With the sending domain's **Drop suppressed recipients** setting off, the default, `send()` throws `E_RECIPIENT_SUPPRESSED` and nothing is sent. With it on, Email Service removes suppressed recipients and sends to the rest. A send refused for suppression does not count toward the monthly quota.
- How do you confirm an order confirmation was actually delivered?`send()` resolving only means Email Service accepted the message. Check the Email Sending logs for *Delivered* or *Delivery failed*, or subscribe a queue to Email Sending events such as `message.delivered` and `message.bounced`. The Email Routing summary is the wrong place, because it lists Worker-sent mail as dropped.
- When env.EMAIL.send() resolves, the customer's mail server has accepted the message.
- On Workers Free a send_email binding can mail any customer address.
- An unrestricted send_email binding may send from any domain on the internet.
- Email Service is a good fit for the weekly marketing newsletter.
- A failed send() resolves with success: false instead of throwing.
Assumes Email Service as of 2026-10-10: Email Sending joined Email Routing in public beta on 2026-04-16 and needs the Workers Paid plan for arbitrary recipients.