Skip to content

Cloudflare setup

Create the Cloudflare API token

EmailFlare uses one API token to set up sending domains, publish DNS records, route inbound mail and send. Give it these permissions and no more.

Permissions

These are the permissions the code uses. Each row names the Cloudflare API call that needs it, so you can leave out anything for a feature you will not use.

Cloudflare API token permissions
PermissionLevelAccessUsed for
Email SendingAccountEditSending mail through the Cloudflare API, and creating a sending subdomain for each domain you enable.
ZoneZoneReadListing your zones for the domain picker, and finding the zone that owns a hostname.
DNSZoneEditPublishing the DNS records Email Sending asks for (SPF, DKIM and return path).
Zone SettingsZoneEditTurning on Email Routing for the zone. Cloudflare gates the enable call on this permission, not on Email Routing Rules.
Email Routing RulesZoneEditSetting the zone's catch-all rule so inbound mail goes to your Worker.
Account SettingsAccountReadOptional. Lets the dashboard show your account name in the token status.

Create the token

  1. Open the API Tokens page

    Go to dash.cloudflare.com/profile/api-tokens, select Create Token, then choose Create Custom Token at the bottom of the template list.

  2. Name the token

    Use a name you will recognise later, such as emailflare-production.

  3. Add the permissions

    Under Permissions, add one row for each permission in the table above. Pick the level (Account or Zone), the permission, then the access.

  4. Set the resources

    Under Account Resources, include your account. Under Zone Resources, include only the zones you will send from and receive on. A token limited to those zones does less damage if it leaks.

  5. Create it and copy the value

    Select Continue to summary, check the list, then Create Token. Cloudflare shows the token once. Copy it into a password manager before you leave the page.

  6. Find your account ID

    In the Cloudflare dashboard, open Workers & Pages. The Account ID is a 32-character hex string in the sidebar. It also appears in the dashboard URL after dash.cloudflare.com/.

Add it to the Worker

Both values are secrets. For a deployed Worker, set them with the just recipe or wrangler secret put:

Production
just dashboard-secret CF_API_TOKEN
just dashboard-secret CF_ACCOUNT_ID

For local development, put them in apps/dashboard/.dev.vars, which is gitignored:

apps/dashboard/.dev.vars
CF_API_TOKEN=your_token_value
CF_ACCOUNT_ID=your_account_id

Check it works

After the Worker has both secrets, the dashboard checks the token with Cloudflare and reports whether it is active and which account it belongs to. Then enable a domain. If a permission is missing, the dashboard says so and shows what is left to do by hand.

Troubleshooting

Token problems and fixes
SymptomCauseFix
Domain setup says the token is missing a permissionOne of Email Sending, Zone Read or the other permissions above is absent, or the zone is outside the token's Zone Resources.Edit the token, compare it with the table, and include the zone under Zone Resources.
The domain is saved but inbound mail does not arriveZone Settings: Edit or Email Routing Rules: Edit is missing, so EmailFlare could not enable routing or set the catch-all.Add both permissions, or set the catch-all by hand. See the deployment guide.
DNS records are listed for you to add manuallyDNS: Edit is missing, or a record could not be written.Add DNS: Edit to the token, or create the listed records in your DNS settings.
The domain picker is emptyZone: Read is missing, or the token's Zone Resources exclude your domain.Add Zone: Read and include the zone.
Token status says the token is not activeThe token has expired, was rolled or was deleted.Create a new token and set CF_API_TOKEN again.
Token status cannot find the accountCF_ACCOUNT_ID is wrong, or the token has no Account Settings: Read permission.Check the ID. Account Settings: Read only affects the status display.