Runtime APIs
Send email from a Worker through an SMTP server that you configure, and receive email in its email() handler.
Runs on Your SMTP server, with inbound email on /cdn-cgi/handler/email
- Works
send()with anEmailMessageor a message object, the address limits, andemail()withforward()andreply()- Differs
- Mail goes out through the SMTP server in
ORANGE_EMAIL_SMTP_URL. Inbound mail arrives as a POST to/cdn-cgi/handler/email. - Missing
- Email Routing, and Cloudflare's sender-domain and verified-destination checks
- Migration
- Not needed Mail goes through your SMTP server.
- Configure
send_email- Checks
- 2 pass
On OpenOrange, your Worker sends email through an SMTP server that you choose,
such as Amazon SES or Resend. It receives email in its email() handler, as on
Cloudflare.
Quickstart
You need an SMTP server. To try it on your machine, run Mailpit, which catches mail and sends nothing out:
docker run --rm -p 1025:1025 -p 8025:8025 axllent/mailpit:v1.27
-
Bind the sender
Add a
send_emailentry towrangler.jsonc, as for Wrangler.{ "name": "send-email", "main": "src/index.ts", "compatibility_date": "2026-09-03", "send_email": [{ "name": "EMAIL", "allowed_destination_addresses": ["team@example.com"] }] } -
Send a message
Pass a message object to
send(), as for Cloudflare’s Email Service. Orange builds the MIME.interface Env { EMAIL: SendEmail; } export default { async fetch(request, env): Promise<Response> { const { messageId } = await env.EMAIL.send({ from: "me@example.com", to: "team@example.com", subject: "Hello", text: "Sent from my Worker.", }); return Response.json({ messageId }); }, } satisfies ExportedHandler<Env>; -
Point it at your SMTP server
Put the server’s URL in
.dev.vars. Choose a provider has the URL for Amazon SES, Resend, Postmark, SendGrid, and Mailgun.ORANGE_EMAIL_SMTP_URL=smtp://127.0.0.1:1025On a cluster, pass the same file with
orange deploy --secrets-file .dev.vars. -
Run it
orange devshows the binding on SMTP.orange dev Binding Resource Runs on env.EMAIL Send Email SMTP · ORANGE_EMAIL_SMTP_URLSend one. The Worker returns the message’s
messageId, and the message shows in Mailpit athttp://127.0.0.1:8025.curl localhost:8787
How it works
send()builds the message, checks the binding’s address limits, and hands it to your SMTP server.- A message POSTed to
/cdn-cgi/handler/emailruns youremail()handler, as inwrangler dev. Point your provider’s inbound webhook at it. See Receive email. message.forward()andmessage.reply()send through the same SMTP server.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
| Feature | Status | Notes |
|---|---|---|
send() with an EmailMessage from cloudflare:email | Supported | Your own MIME, sent as it is. See Both forms of send(). |
send() with a message object | Partial | from, to, cc, bcc, replyTo, subject, text, html, headers, and attachments. to is required, also with cc or bcc, and an attachment’s content must be a base64 string. |
destination_address, allowed_destination_addresses, and allowed_sender_addresses | Supported | Checked before anything is sent. See Address limits. |
| Sender-domain and verified-destination checks | Not supported | Your SMTP provider does its own checks. |
The email() handler | Supported | Runs when a message is POSTed to /cdn-cgi/handler/email. See Receive email. |
message.forward() | Supported | Adds only X- headers, as on Cloudflare. |
message.reply() with an EmailMessage | Supported | |
message.reply() with a message object | Not supported | Throws TypeError: message.reply() takes an EmailMessage from cloudflare:email. |
message.setReject() | Supported | The POST gets 400. |
| Email Routing: MX records and routing rules | Not supported | Cloudflare-only. Your provider receives the mail and POSTs it to the route. |
Three differences reach most projects:
- Inbound mail needs a provider’s webhook. Orange has no mail server, so a provider such as SendGrid or Mailgun must receive the mail and POST it to the Worker.
forward()andreply()throw withoutORANGE_EMAIL_SMTP_URL.wrangler devreports success and delivers nothing. On Orange, that would lose mail silently.- Orange does not check sender domains or verified destinations, which Cloudflare does. Your SMTP provider does its own checks.
Limits
| What | Limit | What happens over it |
|---|---|---|
| One inbound message | 25 MiB, Workers’ production limit, which wrangler dev also applies | The POST gets 400 Email message size is bigger than the production size limit of 25 MiB. |
| Senders and recipients | The binding’s address limits | send() throws before it sends anything, and names the address and the field. |
| Outgoing message size and sending rate | Your SMTP provider’s | The server refuses the message, and send() throws Sending email through <server> failed: <cause>. |
Choose a provider
Set ORANGE_EMAIL_SMTP_URL to your provider’s SMTP server. URL-encode the user
name and password, for example / as %2F, + as %2B, and = as %3D.
| Provider | ORANGE_EMAIL_SMTP_URL | User name and password |
|---|---|---|
| Amazon SES | smtp://<SMTP user name>:<SMTP password>@email-smtp.<region>.amazonaws.com:587 | SES SMTP credentials for that region. The password is not your AWS secret access key. Use smtps:// with port 465 for TLS from the start. SMTP endpoints |
| Resend | smtps://resend:<API key>@smtp.resend.com:465 | resend and your API key. Port 587 with smtp:// also works. |
| Postmark | smtp://<server API token>:<server API token>@smtp.postmarkapp.com:587 | The server API token for both, or an SMTP token’s access key and secret key. Postmark has no port 465. |
| SendGrid | smtps://apikey:<API key>@smtp.sendgrid.net:465 | The word apikey and your API key. Port 587 with smtp:// also works. |
| Mailgun | smtp://<SMTP login>:<SMTP password>@smtp.mailgun.org:587 | The SMTP credentials of your sending domain. For an EU domain, use smtp.eu.mailgun.org. |
| Any other SMTP server | smtp://<user>:<password>@<host>:587 | Most providers have an SMTP endpoint. |
| Mailpit on your machine | smtp://127.0.0.1:1025 | None. Mailpit sends nothing out, and shows the mail at http://127.0.0.1:8025. |
To pick a Postmark message stream, add the X-PM-Message-Stream header to the
message.
Settings
| Variable | Value |
|---|---|
ORANGE_EMAIL_SMTP_URL | smtp://user:password@smtp.example.com:587, with STARTTLS when the server offers it, or smtps://user:password@smtp.example.com:465, with TLS from the start. send(), forward(), and reply() all use it. |
ORANGE_EMAIL_INBOUND_SECRET | The secret for the inbound route. See Receive email. |
- Orange reads each from the shell environment,
.dev.vars, or.env. A value from the shell wins. - On a cluster, set them on the runner pool as secrets, with
orange deploy --secrets-file. - A URL with another scheme stops the Worker from starting, with
ORANGE_EMAIL_SMTP_URL must start with smtp:// or smtps://, not <scheme>//. A value that is not a URL fails withORANGE_EMAIL_SMTP_URL must be a URL such as smtp://user:password@smtp.example.com:587. orange doctorreportsenv.EMAIL · smtp://<host>:<port>, without the credentials. Without the variable, it reportsenv.EMAIL has no SMTP server, so its calls throwas an action. With another scheme, it fails withORANGE_EMAIL_SMTP_URL must be a URL that starts with smtp:// or smtps://.
Both forms of send()
import { EmailMessage } from "cloudflare:email";
// Your own MIME message, sent as it is.
await env.EMAIL.send(new EmailMessage("me@example.com", "team@example.com", rawMime));
// A message object, as in Cloudflare's Email Service. OpenOrange builds the MIME.
const { messageId } = await env.EMAIL.send({
from: { email: "me@example.com", name: "Me" },
to: "team@example.com",
cc: ["lead@example.com"],
bcc: "archive@example.com",
replyTo: "help@example.com",
subject: "Report",
text: "The report is attached.",
html: "<p>The report is attached.</p>",
headers: { "X-Report": "weekly" },
attachments: [{ content: base64Pdf, filename: "report.pdf", type: "application/pdf", disposition: "attachment" }],
});- Both forms return
{ messageId }. For anEmailMessage,messageIdis itsMessage-IDheader, or""when it has none. For a message object, it is theMessage-IDthat Orange generates. - Bcc recipients get the message through the SMTP envelope, so the message
carries no
Bccheader. - An address is a string or
{ email, name }.to,cc, andbccalso take an array. - An attachment needs a base64
contentstring and afilename.typesets its content type.disposition: "inline"with acontentIdmakes it an inline part.
Address limits
As on Cloudflare, the binding refuses a message before it sends anything when an address breaks its limits:
| Field | Effect | Error |
|---|---|---|
destination_address | Every recipient, including Cc and Bcc, must be this address. | Send Email binding "EMAIL" may only send to its destination_address, not <address> |
allowed_destination_addresses | Every recipient must be in the list. | Send Email binding "EMAIL" may not send to <address>: it is not in allowed_destination_addresses |
allowed_sender_addresses | The sender must be in the list. | Send Email binding "EMAIL" may not send from <address>: it is not in allowed_sender_addresses |
Receive email
A Worker’s email() handler runs when a message is POSTed to
/cdn-cgi/handler/email, the route that wrangler dev also serves. Point your
email provider’s inbound webhook, or any script that can POST a raw message,
at it.
orange serveserves the route only whenORANGE_EMAIL_INBOUND_SECRETis set. Without it, the POST reaches the Worker’sfetch()like any other request.orange devserves the route without the secret, aswrangler devdoes, and checks the secret when it is set.
Send the secret in one of two ways:
Authorization: Bearer <secret>.- As the Basic auth password, which most providers allow in the webhook URL:
https://inbound:<secret>@worker.example.com/cdn-cgi/handler/email.
A wrong or missing secret gets 401 with
Unauthorized: send ORANGE_EMAIL_INBOUND_SECRET as a Bearer token or as the Basic auth password.,
and email() does not run.
curl -X POST "https://worker.example.com/cdn-cgi/handler/email?from=alice@example.org&to=inbox@example.com" \
-H "Authorization: Bearer $ORANGE_EMAIL_INBOUND_SECRET" \
--data-binary @message.eml
| Response | When |
|---|---|
200 Worker successfully processed email | email() returned |
400 | No envelope, a message over 25 MiB, a message without a Message-ID, or message.setReject(), with Worker rejected email with the following reason: <reason> |
401 | A wrong or missing secret |
500 | email() threw, and the body has the error. Also when the Worker exports no email() handler: Worker does not export an email() handler. |
The other 400 bodies are wrangler dev’s:
Invalid email. Your request must include URL parameters specifying the `from` and `to` addresses, as well as an email in the body,
and Email could not be parsed: invalid or no message id provided.
email() gets a ForwardableEmailMessage with from, to, headers, raw,
rawSize, and setReject(). As on Cloudflare, headers and raw have no
Bcc header. A folded header reads as one line in headers. A header name
that Headers refuses stays only in raw.
What the route accepts
| Body | Envelope |
|---|---|
| A raw MIME message, any content type | ?from=<sender>&to=<recipient> in the URL |
multipart/form-data from SendGrid Inbound Parse with POST the raw, full MIME message on: the email field | The envelope field, or the URL |
multipart/form-data from Mailgun with the raw MIME: the body-mime field | The sender and recipient fields, or the URL |
Inbound providers
| Provider | Set up |
|---|---|
| SendGrid Inbound Parse | Set the destination URL to https://inbound:<secret>@<your host>/cdn-cgi/handler/email, and turn on POST the raw, full MIME message. |
| Mailgun routes | Forward to https://inbound:<secret>@<your host>/cdn-cgi/handler/email?format=mime. Mailgun sends body-mime only when the URL ends in mime. |
| Amazon SES, Postmark, Resend | Not directly. They POST JSON, which the route does not read. Use a small relay that gets the raw message and POSTs it with ?from=&to=. |
forward() and reply()
import { EmailMessage } from "cloudflare:email";
export default {
async email(message) {
await message.forward("team@example.com", new Headers({ "X-Seen": "yes" }));
await message.reply(new EmailMessage(message.to, message.from, replyMime));
},
};forward(rcptTo, headers)sends the message as it arrived, from the address it was sent to, as a relay does, sorcptTois only its envelope recipient.headersmay add onlyX-headers, as on Cloudflare. Another header throwsTypeError: message.forward() may only add X- headers, not <name>.reply(message)sends theEmailMessagethat you build, including itsIn-Reply-Toheader.- Both return
{ messageId }: the forwarded message’sMessage-ID, or the reply’s. - Without
ORANGE_EMAIL_SMTP_URL, both throw, such asmessage.forward() needs ORANGE_EMAIL_SMTP_URL. Set it to your SMTP server, such as smtp://user:password@smtp.example.com:587. - When the SMTP server is down, both throw
Sending email through ... failed, so the POST gets500and your provider can retry it.
Errors
| Situation | What send() does |
|---|---|
ORANGE_EMAIL_SMTP_URL is not set | Throws Send Email binding "EMAIL" is not supported by OpenOrange. Set ORANGE_EMAIL_SMTP_URL to your SMTP server, such as smtp://user:password@smtp.example.com:587, or send email through your provider's HTTP API with fetch(). |
| The SMTP server is down or refuses the message | Throws Sending email through smtp://smtp.example.com:587 failed: <cause>. The message never names the user name or password. |
| An address breaks a limit | Throws, and names the address and the field. See Address limits. |
A message object has no from, to, subject, or text or html | Throws a TypeError, such as send(): subject is required. |
An attachment has no base64 content string or no filename | Throws TypeError: send(): each attachment needs base64 content and a filename. |
Deviations
These add to the differences under Compatibility.
orange devserves/cdn-cgi/handler/emailwithout a secret, aswrangler devdoes.orange serveserves it only withORANGE_EMAIL_INBOUND_SECRET, so nobody can forge a deployed Worker’s mail.- Every Send Email binding,
forward(), andreply()share the one SMTP server inORANGE_EMAIL_SMTP_URL.
Conformance
tests/cli/orange-email.test.tsrunsorange devagainst Mailpit in Docker, a real SMTP server. AnEmailMessageand a message object with Cc, Bcc, and an attachment arrive, and a recipient outsideallowed_destination_addressesis refused. WithoutORANGE_EMAIL_SMTP_URL,send()names the setting, and with the server down, it names the server without its password. A raw message POSTed to/cdn-cgi/handler/emailrunsemail(), whoseforward()andreply()arrive, a malformed message is refused, and aforward()to a server that is down fails the POST with500.tests/events/email-handler.test.tsPOSTs mail toorange devand expects the output ofwrangler dev4.129.0 for the same fixture: Bcc removed, folded headers,setReject(), a handler that throws, a missing envelope, and a missingMessage-ID. Without an SMTP server,forward()andreply()fail.- The
emailconformance probe, and thevmailandagentic-inboxreal projects, send and receive mail through the binding. tests/cli/doctor.test.tschecks theorange doctorrow and settings check of a Send Email binding.SendEmail,cloudflare:email, and theemailevent are not registered in the type-conformance checks.
Recorded results
Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.
Send Email
| Check | Status | Results |
|---|---|---|
Send Email (send_email) | Works |
|
Inbound email: email(), forward(), and reply() | Works |
|