Apps that receive email

Some apps receive email: an inbox, a mail-to-chat bridge, a newsletter archive. They run an email handler on their Worker, and Cloudflare Email Routing delivers mail to it. When such an app's catalog entry says which addresses it wants, Appflare sets up Email Routing for you during the install.

What you needCopy Anchor Link

• A domain (a zone) on this Cloudflare account, with the status Active, that uses Cloudflare as its DNS provider. Email Routing does not work on zones whose DNS is hosted elsewhere.
• A Cloudflare token for Appflare with these permissions on that zone and account:

The token link in setup includes all of them. Zone and DNS are shared with custom domains.

The link names the two Email Routing permissions with keys that Cloudflare's token template page does not list (email_routing_rule and email_routing_address); they follow the dashboard's naming for every listed key. Once, after opening the link, check that Email Routing Rules (Edit) and Email Routing Addresses (Read) are selected. If they are not, add them by hand. If the token lacks one, the install form says which. Edit the Appflare token under API Tokens in the Cloudflare dashboard, add the permissions, and save; an edited token keeps its value. Appflare connected with Cloudflare sign-in has all of them already.

InstallingCopy Anchor Link

For an app that receives email, the install form has an Email section:

1. Choose the zone whose email the app should receive. Only active zones are listed.
2. Appflare reads the zone and shows what the install will set up there, without changing anything yet.
3. Install as usual. The Install button stays off while something is in the way.

The install then:

• turns Email Routing on for the zone if it is off. Cloudflare adds its MX records (route1, route2 and route3.mx.cloudflare.net), an SPF record (v=spf1 include:_spf.mx.cloudflare.net ~all) and a DKIM record, and locks them;
• creates one routing rule per address the app asks for, such as inbox@example.com, that sends mail to the app's Worker;
• if the app asks for the catch-all, points the zone's catch-all rule at the Worker, so mail to every other address at the zone reaches the app.

These show on the app's page under Email.

An app made of several Workers has one of them receive its mail: the one its catalog entry names, or else the Worker that serves the app. The rules and the catch-all deliver to that Worker, and the app's page says which one when it is not the main one. A Worker that is not reachable from the internet can still receive mail: Email Routing hands mail to a Worker by name, not over the web.

Some apps also need to know the domain in their own settings, for example to send mail from accounts@example.com. Their catalog entry fills the setting in with the domain you chose, and with its zone ID where the app needs that. You can see the values on the app's Settings tab.

Appflare checks the zone first and refuses, before creating anything, when:

• the zone's mail goes to another provider (it has other MX records) and Email Routing is off. Turning it on would replace those records, so Appflare leaves that choice to you: turn Email Routing on in the Cloudflare dashboard if you mean to, or choose another zone;
• an address the app wants already has a routing rule that delivers somewhere else;
• the catch-all is on and already delivers somewhere else (a catch-all set to drop counts as free);
• the zone would pass Cloudflare's limit of 200 routing rules.

Appflare never replaces a rule it did not create.

Sending emailCopy Anchor Link

An app with a send_email binding can also send. Cloudflare delivers to your account's verified destination addresses for free on every plan: add them in the Cloudflare dashboard under Email Service, Email Routing, Destination addresses, and click the link in the verification email. Sending to any other address needs Email Sending, which requires the Workers Paid plan and a sending domain set up in Email Service (3,000 emails a month are included, then $0.35 per 1,000). Appflare changes nothing for sending; the app's page reminds you of this under Next steps, and the install form lists the addresses already verified.

UninstallingCopy Anchor Link

The uninstall undoes the Email Routing setup first, before it deletes the Worker, so no mail is sent to a Worker that no longer exists:

1. It deletes each routing rule the install created. A rule you already deleted counts as removed.
2. It puts the catch-all back as the install found it (for example off, or set to drop), but only if it is still on and delivers to the app. A catch-all you pointed elsewhere or turned off since is left alone.
3. If this install turned Email Routing on for the zone, it turns it off again, which removes the MX records, but only when no other routing rule is left there and the catch-all is off or set to drop. Otherwise Email Routing stays on.

So Email Routing stays on after an uninstall when:

• another install on the same zone still has routing rules or the catch-all there;
• another install (or you, in the dashboard) turned it on. Only the install that turned it on turns it off. If two email apps share a zone and the one that turned routing on is uninstalled first, routing stays on for the other, and uninstalling the other later leaves it on too. Turn it off in the dashboard (Email Service, Email Routing, Settings) when no app needs it.

If the install found Email Routing already on, the uninstall never turns it off.

Moving to another zoneCopy Anchor Link

To receive email for another zone, change it on the Settings tab of the app's page; see Move email to another zone. The new zone is set up first, then the old one is cleaned up as described above. When the app's settings use the domain, saving deploys them again with the new one; otherwise nothing is deployed.

Updates and rollbacksCopy Anchor Link

When a new version receives other email than the one installed, the update dialog says what changes before you start it, and automatic updates and Update all leave the update for you. The update changes Email Routing to match once the new version serves, on the zone the app receives email for: it adds the routing rules and catch-all the version asks for (with the same checks as an install), then removes the ones it no longer needs (the same way as an uninstall). A rollback does the same for the version it returns to, so it puts back what the update changed. When a new version of an app of several Workers has another of its Workers receive the mail, the update points the app's routing rules and catch-all at that Worker in place, and a rollback points them back. A version that receives no email removes every route of the app, and turns Email Routing off again where the install turned it on and nothing else uses it.

Appflare never changes a routing rule or catch-all it did not set up. If the new version asks for an address that already has a rule, or for the catch-all while it already sends mail somewhere, that part is left out and the job log says so; the rest is set up, and the next update or rollback tries again. The same goes for a change Cloudflare refuses (a missing token permission, say): the version still serves, and the job log says what is left. To finish it sooner, set up the email again. If the app did not receive email before, the update cannot know which zone to use: choose it on the Settings tab of the app's page.

A rollback does not move email back to a zone it left.

Set up email againCopy Anchor Link

When an update or a rollback left part of the app's email out, the app's page says Part of the app's email is not set up under Email on the Domains tab and in the Email group of the Settings tab, with what is missing: an address that is not routed to the app, the catch-all, or a routing rule Appflare set up that the installed version no longer asks for. Appflare works this out from its own records of what it set up, so the note stays until those records match the installed version. It does not read the zone for this: a route deleted by hand in the dashboard is not noticed here, and a catch-all on record that no longer sends mail to the app is checked again only by the next update or rollback.

To finish it without waiting for the next update:

1. Delete or change what was in the way in the Cloudflare dashboard (Email Service, Email Routing): the rule another address already had, or the catch-all that sends mail somewhere else. The job log of the update or rollback names it.
2. On the Settings tab, select Set up email again. Admins only, and not while another job of the app runs. The confirmation lists each rule it sets up or removes.
3. Confirm. The page opens the job's log.

The job sets up only what the installed version asks for, on the zone the app receives email for, and removes only routes Appflare set up that still send mail to the app's Worker; a rule changed since is left alone, and Appflare stops counting it as the app's. It checks the zone first, with the same checks as an install. A rule that already sends an address to the app's Worker counts as set up only when it is on and matches that address alone; a rule that is off, or that also matches on something else such as the sender, is in the way like any other. If a routing rule or catch-all Appflare did not set up is still in the way, or the token lacks a permission, it stops before it changes anything, and its log says what to delete or change in the dashboard. Nothing is deployed: routing rules name the Worker, not a version. Running it again once everything is set up changes nothing.

LimitsCopy Anchor Link

Cloudflare's limits apply:

• 200 routing rules per domain, and 200 destination addresses per account.
• Messages over 25 MiB are rejected.
• The app's email handler runs under the normal Workers limits. On the Workers Free plan, a handler that does heavy work per message can run out of CPU time and fail to process it; failures show in the Worker's logs.
• An app asks for at most 10 addresses, all in the zone you choose. Subdomains of the zone are not set up.