Email
These commands show email usage and control which recipients a project may send to. See Email for the runtime API.
On this pageCheck email usage and logs · Manage allowed destinations · Verify sending setup
Email commands find the project in the same order as deploy: --project, then VOID_PROJECT, then the linked project. void email setup and void email status --platform cloudflare are different. They act on your own Cloudflare account through void cloudflare login and need no SDK project.
void email usage
void email usage [--project <name>]Shows this month's recipient attempts, inbound receipts, the monthly attempt limit and what is left. Reserved submissions count toward the limit. Started attempts stay charged even if delivery fails or the outcome is unknown. The output flags a suspended project.
void email logs
void email logs [--limit <n>] [--project <name>]Shows recent email metadata, kept for 30 days: timestamp, direction, operation ID, recipient and state. --limit takes 1–100. Subjects, bodies and attachments are not stored. Provider acceptance does not prove mailbox delivery. Check unknown outcomes before you retry.
void email destinations
void email destinations [--project <name>]Lists the project's recipient addresses and their state: verified, pending or failed. Outbound mail only goes to verified addresses.
void email allow
void email allow <address> [--project <name>]Adds one recipient to the project's destination list. Follow these steps:
- Run
void email allow <address>. Cloudflare emails a verification link to that address. - The recipient clicks the link. They need no SDK or Cloudflare account.
- Run
void email destinations. This listing records the click. Until then, sends to that address returnUNVERIFIED_DESTINATION.
If the link did not arrive or has expired, run void email allow <address> again while the address is pending. The CLI sends a new link or tells you how to get one.
The owner's email is added when the project is created. It still needs verification, unless Cloudflare verified it for an earlier project. Click the link in that email, then run void email destinations. Until then, sends to yourself return UNVERIFIED_DESTINATION.
void email disallow
void email disallow <address> [--project <name>]Removes one recipient from the project's destination list. New sends to that address are refused at once. Attempts already accepted may still finish. No deploy is needed.
void email domain
void email domain <add|status|list|sync|rotate-secret|remove> [<domain>] [--project <name>]Send and receive mail at your own domain, on a Cloudflare zone you own and register to the project. This works on the SDK platform only. On your own Cloudflare account, the mail domain comes from email.from (see void email setup). For a walkthrough, see Your own domain on the platform.
void email domain add
void email domain add <domain> [--project <name>]Registers an exact domain with the project, using a scoped Cloudflare API token.
Requires: a scoped Cloudflare API token
The CLI opens a token template and accepts a masked paste. Create the token in your own Cloudflare account. Never put it in project files or chat.
The CLI asks you to confirm the account and zone limits. Credentials are encrypted for the zone connection.
Custom inbound email needs a Cloudflare zone apex, because its catch-all does not cover subdomains. Existing MX records and catch-alls are kept. If the apex already receives mail, use another zone apex or the platform's shared address. Each custom apex belongs to one project. Setup returns an operation ID. You can check an interrupted request without starting over.
void email domain status
void email domain status <domain> [--project <name>]Shows recorded inbound, outbound and management readiness, when it was observed and the latest operation. Use sync to reconcile setup and refresh readiness.
void email domain list
void email domain list [--project <name>]Lists the project's registered email domains and their readiness.
void email domain sync
void email domain sync <domain> [--project <name>]Reconciles the domain connection and refreshes readiness. Sync does not rotate the secret. A blocked or uncertain operation exits with an error and names the operation to check.
void email domain rotate-secret
Rotates the connection secret that this domain shares with other domains on the same zone. Inbound delivery must be ready. If setup is incomplete, run void email domain sync <domain> first.
Now you will rotate the email domain secret.
void email domain rotate-secret <domain> [--project <name>]Example output: a confirmation that the new secret is active.
Check an uncertain result before you retry.
void email domain remove
void email domain remove <domain> [--project <name>]Turns off the domain assignment and records the cleanup. Zone resources that another domain uses stay available. Unfinished or uncertain cleanup stays recorded until it can be reconciled safely.
void email status
void email status --platform cloudflareChecks the domain in email.from: permissions, DNS, routing, sending, handler addresses and the email binding. It exits with an error when setup is incomplete. On Workers Free, setup can be ready with sending limited to verified recipients. After you upgrade to Workers Paid, run void email setup --platform cloudflare.
void email status only reads your own Cloudflare account, so --platform cloudflare is required. On the SDK platform, use void email usage and void email destinations.
void email setup
void email setup --platform cloudflareSets up email before you deploy from CI. It needs email.from in void.config.ts, an interactive terminal and Cloudflare email permissions.
The SDK shows the planned DNS, routing, plus-addressing and sending changes. It asks before applying them. Commit void.lock.json, then run void deploy --platform cloudflare --require-email in CI.
On Workers Free, inbound mail and sends to verified recipients still work. After you upgrade to Workers Paid, run this command again to allow any recipient. See Email setup.
