Troubleshooting

Diagnose Email Service setup#

Use the locked Wrangler version installed by pnpm install --frozen-lockfile. These commands inspect account and domain state:

pnpm exec wrangler --version
pnpm exec wrangler whoami
pnpm exec wrangler email sending list
pnpm exec wrangler email sending settings example.com
pnpm exec wrangler email sending dns get example.com
pnpm exec wrangler email routing list
pnpm exec wrangler email routing settings example.com
pnpm exec wrangler email routing dns get example.com

Replace example.com with your zone. If wrangler email is missing, check that you used the repository's frozen lockfile rather than a global Wrangler installation. For authorization errors, check the selected account, token expiry, account role, and setup-token scopes. Use pnpm exec wrangler login to refresh deployment OAuth when needed. Do not print or share the OAuth token to diagnose a failed API request.

If sending is not verified, compare the sending DNS report with the zone's SPF, DKIM, and DMARC records. Do not delete unrelated records or add a second SPF record to fix a conflict. Review the wizard's DNS changes first. If Email Service accepts a message but it never arrives, inspect its delivery events. Check Sandbox restrictions, recipient limits, suppression, and the recipient's spam folder.

If receiving fails, inspect MX records, Email Routing status, the catch-all Worker target, and Workflow errors. For missing delivery events, inspect the cf-email-events queue and domain event subscription. Check the dead-letter queues for exhausted retries. A healthy Worker HTTP endpoint alone does not check those paths.