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.
| Permission | Level | Access | Used for |
|---|---|---|---|
| Email Sending | Account | Edit | Sending mail through the Cloudflare API, and creating a sending subdomain for each domain you enable. |
| Zone | Zone | Read | Listing your zones for the domain picker, and finding the zone that owns a hostname. |
| DNS | Zone | Edit | Publishing the DNS records Email Sending asks for (SPF, DKIM and return path). |
| Zone Settings | Zone | Edit | Turning on Email Routing for the zone. Cloudflare gates the enable call on this permission, not on Email Routing Rules. |
| Email Routing Rules | Zone | Edit | Setting the zone's catch-all rule so inbound mail goes to your Worker. |
| Account Settings | Account | Read | Optional. Lets the dashboard show your account name in the token status. |
Create the token
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.
Name the token
Use a name you will recognise later, such as
emailflare-production.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.
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.
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.
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:
just dashboard-secret CF_API_TOKEN
just dashboard-secret CF_ACCOUNT_IDFor local development, put them in apps/dashboard/.dev.vars, which is gitignored:
CF_API_TOKEN=your_token_value
CF_ACCOUNT_ID=your_account_idCheck 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
| Symptom | Cause | Fix |
|---|---|---|
| Domain setup says the token is missing a permission | One 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 arrive | Zone 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 manually | DNS: 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 empty | Zone: 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 active | The token has expired, was rolled or was deleted. | Create a new token and set CF_API_TOKEN again. |
| Token status cannot find the account | CF_ACCOUNT_ID is wrong, or the token has no Account Settings: Read permission. | Check the ID. Account Settings: Read only affects the status display. |