Skip to main content

Deployment

Publish your aliases to Cloudflare with a single mm deploy that handles the Worker, your inboxes, and the catch-all for you.

Cloudflare Requirements

  • Cloudflare account — Free or paid.
  • A domain managed by Cloudflare DNS — The base domain must be the zone itself or a subdomain of it.
  • Email Routing enabled — Enable it once under Email > Email Routing so Cloudflare adds the MX and SPF records.
  • An API token — With the three permissions listed below.

info

Enabling Email Routing changes your DNS, so Mailmask leaves that step to you. If it isn't enabled, deploy stops with a message pointing to the dashboard.

API Token Permissions

Create a custom token at dash.cloudflare.com/profile/api-tokens with these permissions.

PermissionWhy it is needed
Account > Workers Scripts > EditPublishes the Worker.
Account > Email Routing Addresses > EditRegisters each destination inbox and checks its verification.
Zone > Email Routing Rules > EditPoints the zone's catch-all rule at the Worker.

Under Account Resources, select your account. Under Zone Resources, select the zone that holds your base domain.

Providing the Token

  • Interactive deploy — Choosing Deploy in the mm menu walks you through creating a token, verifies it, and saves it as CLOUDFLARE_API_TOKEN in a .env file in your config directory.
  • Direct command — mm deploy reads CLOUDFLARE_API_TOKEN from the environment or that .env file. It stops with an error instead of prompting when no valid token is found.

If the token is missing a permission, deploy lists exactly which ones to add. In the interactive menu, it waits while you update the token and then retries.

What Deploy Does

  1. Authenticates — Confirms the API token is valid.
  2. Validates — Checks the config and stops if anything is wrong.
  3. Finds the zone — Locates the Cloudflare zone for your base domain and verifies the token's permissions.
  4. Checks Email Routing — Confirms Cloudflare Email Routing is enabled on the zone.
  5. Registers destinations — Adds any new destination to Email Routing, which triggers a verification email, and lists the ones still unverified.
  6. Generates wrangler.toml — Writes the Worker configuration with your settings, destinations, and aliases.
  7. Publishes the Worker — Runs wrangler deploy.
  8. Points the catch-all — Sets the zone's catch-all rule to send mail to the Worker, unless it already does.
  9. Prints a summary — Lists every alias with its full address, destination, and status.

warning

Pointing the catch-all at the Worker replaces whatever the catch-all did before, and deploy prints the previous action. Explicit Email Routing rules for individual addresses still take precedence over the catch-all.

Verifying Destinations

Cloudflare only forwards to verified inboxes. Until you click the link in the verification email, mail for any alias that uses that destination can't be delivered.

Run mm deploy again after verifying to confirm the warning is gone.

Updating Aliases

Every change to the config reaches Cloudflare on the next deploy. A typical retire-and-redeploy looks like this:

bash
# Stop accepting mail at an address that started getting spam.
mm alias disable velvet-harbor-42

# Ship the change.
mm deploy

Worker Exposure

The generated configuration turns off the workers.dev address and preview URLs. The Worker only handles inbound email, and any web request to it returns 404.