diff --git a/src/content/changelog/email-service/2026-09-05-email-routing-wrangler-addresses.mdx b/src/content/changelog/email-service/2026-09-05-email-routing-wrangler-addresses.mdx new file mode 100644 index 00000000000..0e23f1d7f99 --- /dev/null +++ b/src/content/changelog/email-service/2026-09-05-email-routing-wrangler-addresses.mdx @@ -0,0 +1,24 @@ +--- +title: Configure Email Routing addresses with Wrangler +description: Define inbound Email Routing rules in Wrangler configuration and reconcile them during Worker deployments. +date: 2026-09-05 +--- + +import { WranglerConfig } from "~/components"; + +Wrangler 4.113.0 and later can manage the Email Routing rules that send inbound email to a Worker. Define literal recipient addresses or an apex-domain catch-all with the top-level `addresses` field: + + + +```toml +name = "my-worker" +main = "src/index.ts" +compatibility_date = "$today" +addresses = ["support@example.com", "*@example.com"] +``` + + + +When you deploy the Worker or its triggers, Wrangler shows the planned Email Routing changes and reconciles the managed rules. Purely additive changes apply automatically. Deletions and rule takeovers require confirmation in an interactive environment. + +Refer to [Email routing rules and addresses](/email-service/configuration/email-routing-addresses/#configure-rules-with-wrangler) for configuration and deployment details. diff --git a/src/content/docs/email-service/configuration/email-routing-addresses.mdx b/src/content/docs/email-service/configuration/email-routing-addresses.mdx index b14a81b5816..3e131a3ee84 100644 --- a/src/content/docs/email-service/configuration/email-routing-addresses.mdx +++ b/src/content/docs/email-service/configuration/email-routing-addresses.mdx @@ -8,7 +8,7 @@ products: - email-service --- -import { DashButton } from "~/components"; +import { DashButton, WranglerConfig } from "~/components"; In Email Routing, a routing rule pairs an email pattern with a destination — either a verified email address or a Worker. You can route emails to either: @@ -139,6 +139,40 @@ Once enabled, you can use subaddressing with any of your routing rules. For exam If a routing rule for `user+detail@example.com` already exists, it takes precedence over the rule for `user@example.com`. This prevents breaking existing routing rules and allows certain sub-addresses to be captured by a specific rule. +## Configure rules with Wrangler + +If your routing rules send mail to a [Worker](/email-service/api/route-emails/email-handler/), you can define them in your Worker's [Wrangler configuration file](/workers/wrangler/configuration/) instead of creating them in the dashboard. Add the inbound addresses to the top-level `addresses` field: + +This feature requires Wrangler 4.113.0 or later. + + + +```toml +name = "my-worker" +main = "src/index.ts" +compatibility_date = "$today" +addresses = ["support@example.com", "*@example.com"] +``` + + + +Each entry is either a literal recipient address (for example, `support@example.com`), which creates a routing rule for that address, or a `*@domain` catch-all (for example, `*@example.com`), which configures the [catch-all rule](#catch-all-rule) for that domain. Catch-all entries support apex domains only. To route mail sent to an Email Routing subdomain, list each literal recipient address, such as `support@mail.example.com`. + +Every entry uses the _Send to a Worker_ action to route mail to the Worker you are deploying. + +The `addresses` field is top-level only and applies to every [environment](/workers/wrangler/environments/) of the Worker. Wrangler ignores `addresses` values under `env`. + +If you omit `addresses`, Wrangler does not change Email Routing rules. If you set `addresses` to an empty array, Wrangler removes every Email Routing rule managed by this Worker. + +When you run [`wrangler deploy`](/workers/wrangler/commands/workers/#deploy) or [`wrangler triggers deploy`](/workers/wrangler/commands/workers/#triggers), Wrangler reconciles the Email Routing rules for the addresses you listed. It adds rules for new entries, updates the rules it manages, and removes managed rules that are no longer listed. Wrangler prints the planned changes and asks you to confirm before applying a destructive change, such as deleting or taking over a rule. In non-interactive environments, Wrangler does not apply destructive changes and exits with an error after deploying the Worker. + +To validate your local configuration without deploying or checking remote rules, run `wrangler deploy --dry-run`. + +:::note + +Rules created from `addresses` are managed by your Wrangler configuration file. The dashboard warns you before an edit detaches a managed rule. On the next deploy, Wrangler reports a takeover conflict and asks for confirmation before restoring the configured rule. +::: + ## Next steps - [Email handler](/email-service/api/route-emails/email-handler/) — process emails programmatically with the `email()` handler. diff --git a/src/content/docs/email-service/configuration/subdomains.mdx b/src/content/docs/email-service/configuration/subdomains.mdx index 1c524673aa5..fd5756c1054 100644 --- a/src/content/docs/email-service/configuration/subdomains.mdx +++ b/src/content/docs/email-service/configuration/subdomains.mdx @@ -24,7 +24,7 @@ A zone can have up to 30 domains configured for Email Routing or Email Sending c 3. Select the apex domain, then open **Settings**. 4. Under **Subdomains**, enter the subdomain you want to enable in the inline form and submit it. -Cloudflare adds the required DNS records to the subdomain. Once the records propagate, you can create [routing rules](/email-service/configuration/email-routing-addresses/) on the subdomain in the same way as on the apex domain. +Cloudflare adds the required DNS records to the subdomain. Once the records propagate, you can create [literal routing rules](/email-service/configuration/email-routing-addresses/) for addresses on the subdomain. Catch-all rules are only available for the apex domain. ## Add a subdomain to Email Sending diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index d00bb62f126..40488cec757 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -132,6 +132,10 @@ Top-level keys apply to the Worker as a whole (and therefore all environments). - `keep_vars` - Whether Wrangler should keep variables configured in the dashboard on deploy. Refer to [source of truth](#source-of-truth). + +- `addresses` + - A list of inbound email addresses that [Email Routing](/email-service/configuration/email-routing-addresses/#configure-rules-with-wrangler) routes to this Worker. Each entry is either a literal recipient address (for example, `support@example.com`) or a `*@domain` catch-all (for example, `*@example.com`). Catch-all entries support apex domains only. When you deploy the Worker or its triggers, Wrangler reconciles the Worker's managed Email Routing rules with this list. + - `send_metrics` - Whether Wrangler should send usage data to Cloudflare for this project. Defaults to `true`. You can learn more about this in our [data policy](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md). - `dependencies_instrumentation`