Repository navigation
Troubleshooting
Find the message you saw, then follow the fix. Anything the installer has already done is kept, so running the same command again carries on from where it stopped.
For the full set-up steps, see the set-up guide.
The token must be an active user API token, not your Global API Key.
- Open My Profile › API Tokens.
- Choose Create Token, then Create Custom Token.
- Tick every permission listed by
npx @mrpwob/mail-app help. - Run the installer again and paste the new token.
The message names the missing permission, for example Zone: Read or Workers: Admin. Edit the token in API Tokens, add that permission and run the command again.
If Cloudflare refuses a later step, check the token has everything listed by npx @mrpwob/mail-app help. Since September 2026 Cloudflare asks for Workers: Admin (it used to be called Workers Scripts).
Edit the token and check Account Resources includes the account you want to install on.
Open Workers & Pages in your Cloudflare dashboard once and pick a name when it asks. Then run the installer again.
Open R2 in your Cloudflare dashboard and switch it on. Cloudflare asks for a payment card once, even for its free allowance. Then run the installer again.
Open Zero Trust in your Cloudflare dashboard, choose the Free plan, then run the installer again.
The domain probably still gets its email somewhere else, such as Google or Microsoft. Move that email or switch it off first, then run the installer again.
Not sure? Use a spare domain to try Mail App first.
Something else already uses that web address. Either remove its DNS record in Cloudflare, or pick a different address with --subdomain, for example:
npx @mrpwob/mail-app setup --subdomain webmailReceiving works already. To send:
- Turn on the Workers Paid plan ($5 a month, paid to Cloudflare). The set-up guide has a short video.
- Run
npx @mrpwob/mail-app update --force.
Tokens typed on the command line are saved in your shell history. Paste it when the installer asks, or set CLOUDFLARE_API_TOKEN first.
Check your internet connection (and any VPN or company firewall), then run the command again.
See Why isn't my sign-in code arriving? in the set-up guide's questions. The usual cause is Zero Trust without a plan, or an address that isn't on the sign-in list.
Mail App refuses to open until Cloudflare Access protects it. The installer does this for you. If you installed with the Deploy button or Wrangler, follow Cloudflare Access in the README.
Each person must also be on the Cloudflare Access policy. Mail App can add them itself if the installer's token included the optional API Tokens: Edit permission. Otherwise, add their address under Zero Trust › Access controls › Policies, in the Mail App policy.
- Open your domain's Email › Email Routing and check it's switched on.
- Under Routing rules, check the Catch-all is set to Send to a Worker,
mail-app. - Open Mail App's Setup page. Every light should be green, and it says what to fix if not.
Open Mail App's Setup page and fix anything that isn't green. It checks your SPF, DKIM and DMARC records. Sending also needs the Workers Paid plan and your domain switched on under Email Sending.
These need their own Access application with a Bypass policy, plus PUBLIC_LINKS or PUBLIC_API set to on. The installer sets them up. To do it by hand, see the API and download links in the README.
Ask in Discussions with the exact message you saw (remove your token and any personal details first). If it looks like a bug, open an issue.
Mail App
On paulobrien.dev
Help