From d68f5b23939b45cb0830e631a129518aa3fc722b Mon Sep 17 00:00:00 2001 From: Diogo Santos Date: Mon, 29 Jun 2026 15:03:38 +0100 Subject: [PATCH 1/3] [Email Routing] Document the addresses Wrangler configuration field --- .../configuration/email-routing-addresses.mdx | 28 ++++++++++++++++++- .../docs/workers/wrangler/configuration.mdx | 4 +++ 2 files changed, 31 insertions(+), 1 deletion(-) 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..ec4ab4118fd 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,32 @@ 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: + + + +```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. 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: it applies to every [environment](/workers/wrangler/environments/) of the Worker and cannot be set under `env`. + +When you run [`wrangler deploy`](/workers/wrangler/commands/workers/#deploy), Wrangler reconciles the Email Routing rules for the addresses you listed: it adds rules for new entries, updates the rules it manages, and removes rules it previously created that are no longer listed. Wrangler prints the planned changes and asks you to confirm before applying a destructive change, such as deleting a rule or taking over a rule that is managed elsewhere. To validate your configuration without deploying, run `wrangler deploy --dry-run`. + +:::note + +Rules created from `addresses` are managed by your Wrangler configuration file. If you change one of these rules in the dashboard, a later `wrangler deploy` can overwrite your change to match the configuration file. +::: + ## Next steps - [Email handler](/email-service/api/route-emails/email-handler/) — process emails programmatically with the `email()` handler. diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index d00bb62f126..b2a33a7172f 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`). When you run `wrangler deploy`, each entry creates an Email Routing rule that routes mail to this Worker. + - `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` From 522ab339f0df1c2bb1a4e2d98a0335e0568b57e0 Mon Sep 17 00:00:00 2001 From: Diogo Santos Date: Wed, 15 Jul 2026 13:34:58 +0100 Subject: [PATCH 2/3] [Email Routing] Clarify Wrangler address reconciliation --- .../configuration/email-routing-addresses.mdx | 10 +++++++--- src/content/docs/workers/wrangler/configuration.mdx | 2 +- 2 files changed, 8 insertions(+), 4 deletions(-) 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 ec4ab4118fd..5ece8983ed2 100644 --- a/src/content/docs/email-service/configuration/email-routing-addresses.mdx +++ b/src/content/docs/email-service/configuration/email-routing-addresses.mdx @@ -156,13 +156,17 @@ 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. 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: it applies to every [environment](/workers/wrangler/environments/) of the Worker and cannot be set under `env`. +The `addresses` field is top-level only and applies to every [environment](/workers/wrangler/environments/) of the Worker. Wrangler ignores `addresses` values under `env`. -When you run [`wrangler deploy`](/workers/wrangler/commands/workers/#deploy), Wrangler reconciles the Email Routing rules for the addresses you listed: it adds rules for new entries, updates the rules it manages, and removes rules it previously created that are no longer listed. Wrangler prints the planned changes and asks you to confirm before applying a destructive change, such as deleting a rule or taking over a rule that is managed elsewhere. To validate your configuration without deploying, run `wrangler deploy --dry-run`. +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), 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. If you change one of these rules in the dashboard, a later `wrangler deploy` can overwrite your change to match the configuration file. +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 diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index b2a33a7172f..8346d3796c0 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -134,7 +134,7 @@ Top-level keys apply to the Worker as a whole (and therefore all environments). - 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`). When you run `wrangler deploy`, each entry creates an Email Routing rule that routes mail to this Worker. + - 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`). When you run `wrangler deploy`, 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). From 5a540273b7ddb619300f802feadf2cc79a0052f5 Mon Sep 17 00:00:00 2001 From: Brendan Irvine-Broque Date: Sat, 5 Sep 2026 08:53:22 -0700 Subject: [PATCH 3/3] [Email Routing] Clarify Wrangler address constraints --- ...09-05-email-routing-wrangler-addresses.mdx | 24 +++++++++++++++++++ .../configuration/email-routing-addresses.mdx | 8 +++++-- .../configuration/subdomains.mdx | 2 +- .../docs/workers/wrangler/configuration.mdx | 2 +- 4 files changed, 32 insertions(+), 4 deletions(-) create mode 100644 src/content/changelog/email-service/2026-09-05-email-routing-wrangler-addresses.mdx 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 5ece8983ed2..3e131a3ee84 100644 --- a/src/content/docs/email-service/configuration/email-routing-addresses.mdx +++ b/src/content/docs/email-service/configuration/email-routing-addresses.mdx @@ -143,6 +143,8 @@ If a routing rule for `user+detail@example.com` already exists, it takes precede 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 @@ -154,13 +156,15 @@ 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. Every entry uses the _Send to a Worker_ action to route mail to the Worker you are deploying. +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), 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. +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`. 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 8346d3796c0..40488cec757 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -134,7 +134,7 @@ Top-level keys apply to the Worker as a whole (and therefore all environments). - 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`). When you run `wrangler deploy`, Wrangler reconciles the Worker's managed Email Routing rules with this list. + - 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).