Skip to content
Runtime APIs / Email

Runtime APIs

Email

Send email from a Worker through an SMTP server that you configure, and receive email in its email() handler.

Pluggable

Runs on Your SMTP server, with inbound email on /cdn-cgi/handler/email

Works
send() with an EmailMessage or a message object, the address limits, and email() with forward() and reply()
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
  1. Bind the sender

    Add a send_email entry to wrangler.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"] }]
    }
  2. 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>;
  3. 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:1025

    On a cluster, pass the same file with orange deploy --secrets-file .dev.vars.

  4. Run it

    orange dev shows the binding on SMTP.

    orange dev
      Binding     Resource     Runs on
      env.EMAIL   Send Email   SMTP · ORANGE_EMAIL_SMTP_URL

    Send one. The Worker returns the message’s messageId, and the message shows in Mailpit at http://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/email runs your email() handler, as in wrangler dev. Point your provider’s inbound webhook at it. See Receive email.
  • message.forward() and message.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

FeatureStatusNotes
send() with an EmailMessage from cloudflare:emailSupportedYour own MIME, sent as it is. See Both forms of send().
send() with a message objectPartialfrom, 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_addressesSupportedChecked before anything is sent. See Address limits.
Sender-domain and verified-destination checksNot supportedYour SMTP provider does its own checks.
The email() handlerSupportedRuns when a message is POSTed to /cdn-cgi/handler/email. See Receive email.
message.forward()SupportedAdds only X- headers, as on Cloudflare.
message.reply() with an EmailMessageSupported
message.reply() with a message objectNot supportedThrows TypeError: message.reply() takes an EmailMessage from cloudflare:email.
message.setReject()SupportedThe POST gets 400.
Email Routing: MX records and routing rulesNot supportedCloudflare-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() and reply() throw without ORANGE_EMAIL_SMTP_URL. wrangler dev reports 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

WhatLimitWhat happens over it
One inbound message25 MiB, Workers’ production limit, which wrangler dev also appliesThe POST gets 400 Email message size is bigger than the production size limit of 25 MiB.
Senders and recipientsThe binding’s address limitssend() throws before it sends anything, and names the address and the field.
Outgoing message size and sending rateYour SMTP provider’sThe 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.

ProviderORANGE_EMAIL_SMTP_URLUser name and password
Amazon SESsmtp://<SMTP user name>:<SMTP password>@email-smtp.<region>.amazonaws.com:587SES 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
Resendsmtps://resend:<API key>@smtp.resend.com:465resend and your API key. Port 587 with smtp:// also works.
Postmarksmtp://<server API token>:<server API token>@smtp.postmarkapp.com:587The server API token for both, or an SMTP token’s access key and secret key. Postmark has no port 465.
SendGridsmtps://apikey:<API key>@smtp.sendgrid.net:465The word apikey and your API key. Port 587 with smtp:// also works.
Mailgunsmtp://<SMTP login>:<SMTP password>@smtp.mailgun.org:587The SMTP credentials of your sending domain. For an EU domain, use smtp.eu.mailgun.org.
Any other SMTP serversmtp://<user>:<password>@<host>:587Most providers have an SMTP endpoint.
Mailpit on your machinesmtp://127.0.0.1:1025None. 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

VariableValue
ORANGE_EMAIL_SMTP_URLsmtp://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_SECRETThe 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 with ORANGE_EMAIL_SMTP_URL must be a URL such as smtp://user:password@smtp.example.com:587.
  • orange doctor reports env.EMAIL · smtp://<host>:<port>, without the credentials. Without the variable, it reports env.EMAIL has no SMTP server, so its calls throw as an action. With another scheme, it fails with ORANGE_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 an EmailMessage, messageId is its Message-ID header, or "" when it has none. For a message object, it is the Message-ID that Orange generates.
  • Bcc recipients get the message through the SMTP envelope, so the message carries no Bcc header.
  • An address is a string or { email, name }. to, cc, and bcc also take an array.
  • An attachment needs a base64 content string and a filename. type sets its content type. disposition: "inline" with a contentId makes it an inline part.

Address limits

As on Cloudflare, the binding refuses a message before it sends anything when an address breaks its limits:

FieldEffectError
destination_addressEvery recipient, including Cc and Bcc, must be this address.Send Email binding "EMAIL" may only send to its destination_address, not <address>
allowed_destination_addressesEvery recipient must be in the list.Send Email binding "EMAIL" may not send to <address>: it is not in allowed_destination_addresses
allowed_sender_addressesThe 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 serve serves the route only when ORANGE_EMAIL_INBOUND_SECRET is set. Without it, the POST reaches the Worker’s fetch() like any other request.
  • orange dev serves the route without the secret, as wrangler dev does, 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
ResponseWhen
200 Worker successfully processed emailemail() returned
400No envelope, a message over 25 MiB, a message without a Message-ID, or message.setReject(), with Worker rejected email with the following reason: <reason>
401A wrong or missing secret
500email() 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
BodyEnvelope
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 fieldThe envelope field, or the URL
multipart/form-data from Mailgun with the raw MIME: the body-mime fieldThe sender and recipient fields, or the URL
Inbound providers
ProviderSet up
SendGrid Inbound ParseSet the destination URL to https://inbound:<secret>@<your host>/cdn-cgi/handler/email, and turn on POST the raw, full MIME message.
Mailgun routesForward 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, ResendNot 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, so rcptTo is only its envelope recipient. headers may add only X- headers, as on Cloudflare. Another header throws TypeError: message.forward() may only add X- headers, not <name>.
  • reply(message) sends the EmailMessage that you build, including its In-Reply-To header.
  • Both return { messageId }: the forwarded message’s Message-ID, or the reply’s.
  • Without ORANGE_EMAIL_SMTP_URL, both throw, such as message.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 gets 500 and your provider can retry it.

Errors

SituationWhat send() does
ORANGE_EMAIL_SMTP_URL is not setThrows 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 messageThrows Sending email through smtp://smtp.example.com:587 failed: <cause>. The message never names the user name or password.
An address breaks a limitThrows, and names the address and the field. See Address limits.
A message object has no from, to, subject, or text or htmlThrows a TypeError, such as send(): subject is required.
An attachment has no base64 content string or no filenameThrows TypeError: send(): each attachment needs base64 content and a filename.

Deviations

These add to the differences under Compatibility.

  • orange dev serves /cdn-cgi/handler/email without a secret, as wrangler dev does. orange serve serves it only with ORANGE_EMAIL_INBOUND_SECRET, so nobody can forge a deployed Worker’s mail.
  • Every Send Email binding, forward(), and reply() share the one SMTP server in ORANGE_EMAIL_SMTP_URL.

Conformance

  • tests/cli/orange-email.test.ts runs orange dev against Mailpit in Docker, a real SMTP server. An EmailMessage and a message object with Cc, Bcc, and an attachment arrive, and a recipient outside allowed_destination_addresses is refused. Without ORANGE_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/email runs email(), whose forward() and reply() arrive, a malformed message is refused, and a forward() to a server that is down fails the POST with 500.
  • tests/events/email-handler.test.ts POSTs mail to orange dev and expects the output of wrangler dev 4.129.0 for the same fixture: Bcc removed, folded headers, setReject(), a handler that throws, a missing envelope, and a missing Message-ID. Without an SMTP server, forward() and reply() fail.
  • The email conformance probe, and the vmail and agentic-inbox real projects, send and receive mail through the binding.
  • tests/cli/doctor.test.ts checks the orange doctor row and settings check of a Send Email binding.
  • SendEmail, cloudflare:email, and the email event 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
  • Pass: email: Send Email: an EmailMessage with its own MIME arrives over SMTP
  • Pass: email: Send Email: a message object arrives with its Cc, Bcc, and attachment
  • Pass: email: Send Email: a recipient outside allowed_destination_addresses is refused, and nothing is sent
  • Pass: agentic-inbox: a sent email and a threaded reply are delivered over SMTP through the send_email binding
Inbound email: email(), forward(), and reply() Works
  • Pass: email: Inbound email: a POSTed message runs email(), and forward() sends it on over SMTP
  • Pass: email: Inbound email: reply() sends the Worker's reply, with In-Reply-To
  • Pass: email: Inbound email: setReject() answers 400
  • Pass: email: Inbound email: a wrong secret gets 401, and email() does not run
  • Pass: vmail: an inbound email goes through email() into the mailbox, and the mailbox lists it
  • Pass: vmail: an email to a mailbox that was never created is rejected
  • Pass: agentic-inbox: an inbound email goes through the Worker's email() handler into the inbox