Required permissions for /accounts/<account_id>/email/routing/rules/plan (blocks email addresses deploy)

[ankagar]

Question

What minimum API-token permissions authorize /accounts/<account_id>/email/routing/rules/plan?

I'm hitting Authentication error [code: 10000] on this call during wrangler deploy, with a build token that already grants all permissions the token UI exposes for Email Routing. Trying to figure out what's missing.

Context

wrangler.jsonc uses the top-level addresses field (Email Routing → "Send to a Worker"):

{
  "name": "<worker>",                                   
  "addresses": ["app1@example.com", "app2@example.com"] 
}                                                       

From the cloudflare/workers-sdk#14471 implementation, the addresses deploy step reads a plan and then applies via per-zone rule endpoints. The plan read is what fails for me:

✘ [ERROR] A request to the Cloudflare API
  (/accounts/<account_id>/email/routing/rules/plan) failed.
  Authentication error [code: 10000]

What works vs what doesn't

• ✅ wrangler deploy locally (with super-admin account)
• ❌ wrangler deploy from Workers Builds CI

Permissions of the API Token used in build

<account> (account scope) —
  Email Routing Addresses: Edit, Email Sending: Edit, ... 
All zones (zone scope) —
  Email Routing Rules: Edit, ... 

Environment

• wrangler 4.115.0, Workers Builds CI (non-interactive), bun@1.3.11 / nodejs@24.18.0.

[workers-devprod]

Note

This is an automated, advisory triage report generated by workers-devprod. It is not an official maintainer response — a maintainer will follow up.

🤖 Automated triage report

Issue Triage: #36

Summary

Reporter asks which minimum API-token permissions authorize the account-level /accounts/<account_id>/email/routing/rules/plan endpoint, which fails with Authentication error [code: 10000] during wrangler deploy when using the top-level addresses (Email Routing) config field.

Classification

• Type: Question
• Component: packages/wrangler (Email Routing addresses deploy path, introduced in [wrangler] Apply Email Routing addresses during deploy workers-sdk#14471)
• Severity: Low
• Has Reproduction: Partial (config snippet + exact error message, but no clonable repro and token setup can't be independently verified)
• Quality: Partial

Findings

• Created: not available (metadata beyond the issue body was truncated in context.json)
• Author: ankagar
• Version: not specified
• Labels: not available (truncated)
• Comments: not available (truncated)

Analysis

• The issue is explicitly framed as a Question ("### Question") about API-token permissions, not a confirmed Wrangler bug. The reporter states their build token already grants every Email Routing permission the token UI exposes, yet the account-level .../email/routing/rules/plan read still returns Authentication error [code: 10000].
• Maps clearly to packages/wrangler — the addresses field deploy step (reads a plan, then applies via per-zone rule endpoints) was introduced in PR [wrangler] Apply Email Routing addresses during deploy workers-sdk#14471, which the reporter cites.
• code: 10000 is the generic Cloudflare API "unable to authenticate" / insufficient-permissions error. The root cause is most likely a token-scope gap (the plan endpoint may require a permission the token UI does not surface, or an account-scoped rather than zone-scoped Email Routing permission), not a defect in Wrangler's request code.
• There is a plausible actionable product gap even if the token issue is user-side: Wrangler's error message for the failing plan read could be more specific about the required permission, and the docs for the addresses field could document the needed token scopes.
• Note on data completeness: the pre-fetched context.json is a single line and was truncated at 2000 characters by the available read tools (no bash/network access in this skill). Issue metadata (labels, comment count, created/updated dates, state) could not be read, so staleness and any existing maintainer/reporter responses could not be assessed.

Recommendation

Status: NEEDS MORE INFO

Reasoning: This is a support-style question about token permissions rather than a reproducible Wrangler defect, and it lacks version info and a verifiable repro. A maintainer should confirm the exact required token scope and, if Wrangler's error/docs are unclear, spin off a docs/error-message improvement.

Action: A maintainer should identify the specific API-token permission required for the account-level /email/routing/rules/plan endpoint and reply to the reporter. If the required permission is not exposed in the token UI or not documented, open a follow-up to improve the addresses deploy error message and/or the Email Routing docs. Request the missing version information to rule out a version-specific regression.

Suggested Labels: (none — labels could not be verified against the current issue state; omitting rather than guessing)

Suggested Comment

Thanks for the detailed write-up. The code: 10000 on /accounts/<account_id>/email/routing/rules/plan is the Cloudflare API's generic "insufficient permissions" response, so this is almost certainly a token-scope gap rather than the request Wrangler is making.

To help us pin it down, could you confirm:

• Which wrangler version you're running (wrangler --version)?
• Is the token an account-scoped API token, and does it include an account-level Email Routing permission (as opposed to only zone-level)? The plan endpoint is account-scoped, so a zone-only Email Routing permission won't authorize it.
• Does the same token succeed if you call GET /accounts/<account_id>/email/routing/rules/plan directly with curl?

If it turns out the required permission isn't exposed in the token UI or isn't documented, we'll treat that as a docs/error-message improvement on our side. In the meantime, feel free to ask on our Discord if you'd like quicker back-and-forth.

Structured summary (JSON)

{
  "issueNumber": 14980,
  "title": "What minimum API-token permissions authorize /accounts/<account_id>/email/routing/rules/plan?",
  "githubUrl": "https://github.com/cloudflare/cf-platform-issues/issues/36",
  "recommendation": "NEEDS MORE INFO",
  "difficulty": "medium",
  "reasoning": "This is a token-permissions question (API code 10000, insufficient permissions) about the Email Routing addresses deploy path introduced in cloudflare/workers-sdk#14471, not a confirmed Wrangler bug. It lacks version info and a verifiable reproduction.",
  "suggestedAction": "Ask the reporter for the wrangler version and token scope details; confirm the account-level Email Routing permission required by the /email/routing/rules/plan endpoint, and if it is undocumented or unsurfaced, open a docs/error-message follow-up.",
  "hasSuggestedComment": true,
  "suggestedLabels": []
}