Skip to content

Troubleshooting

Paul O'Brien edited this page Nov 4, 2026 · 1 revision

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.

Installer messages

"Cloudflare didn't accept that API token"

The token must be an active user API token, not your Global API Key.

  1. Open My Profile › API Tokens.
  2. Choose Create Token, then Create Custom Token.
  3. Tick every permission listed by npx @mrpwob/mail-app help.
  4. Run the installer again and paste the new token.

"Your token needs …"

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).

"Your token doesn't reach any Cloudflare account"

Edit the token and check Account Resources includes the account you want to install on.

"Your Cloudflare account doesn't have its free workers.dev address yet"

Open Workers & Pages in your Cloudflare dashboard once and pick a name when it asks. Then run the installer again.

"Storage (R2) isn't switched on for your Cloudflare account yet"

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.

"Sign-in protection uses Cloudflare Zero Trust, which isn't set up on your account yet"

Open Zero Trust in your Cloudflare dashboard, choose the Free plan, then run the installer again.

"We couldn't switch on email for your domain"

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.

"mail.example.com is already in use on your domain"

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 webmail

"Sending to other people needs Cloudflare's Workers Paid plan"

Receiving works already. To send:

  1. Turn on the Workers Paid plan ($5 a month, paid to Cloudflare). The set-up guide has a short video.
  2. Run npx @mrpwob/mail-app update --force.

"Please don't put your token on the command line"

Tokens typed on the command line are saved in your shell history. Paste it when the installer asks, or set CLOUDFLARE_API_TOKEN first.

"We couldn't reach Cloudflare"

Check your internet connection (and any VPN or company firewall), then run the command again.

After installing

My sign-in code isn't arriving

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 won't open and asks for Cloudflare Access

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.

Someone I invited can't sign in

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.

Email isn't arriving

  1. Open your domain's Email › Email Routing and check it's switched on.
  2. Under Routing rules, check the Catch-all is set to Send to a Worker, mail-app.
  3. Open Mail App's Setup page. Every light should be green, and it says what to fix if not.

Email I send goes to spam or bounces

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.

A download link or the API doesn't work

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.

Still stuck?

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.