docs: clarify wildcard MX requirement for random subdomain (#1036)

Random subdomain mailbox creation only generates addresses; mail delivery depends on DNS / Cloudflare Email Routing covering *.<base-domain>. Cloudflare Email Routing does not inherit apex configuration onto subdomains, so a wildcard `*` MX record on the base domain is required for random subdomains to actually receive mail. - Add `[!IMPORTANT]` block in subdomain.md (zh/en) explaining the two deliverable paths: DNS-only wildcard MX (recommended for random subdomains) vs Cloudflare dashboard "Add subdomain" - Link to Cloudflare Email Routing — Subdomains official docs from worker-vars.md and subdomain.md - Instruct copying apex MX records to host `*` preserving each record's priority/target, instead of hardcoding specific MX targets - Shorten frontend `randomSubdomainTip` for CreateAccount and Login views (6 locales: zh/en/de/es/ja/pt-BR), drop Markdown backticks (Vue text interpolation renders them literally), and point users to the docs instead of embedding DNS instructions - Trim overlap between existing `[!NOTE]` and new `[!IMPORTANT]` in subdomain.md - Update CHANGELOG.md / CHANGELOG_EN.md under v1.9.0(main) Closes #1035 Closes #1026 Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-18 00:37:36 +08:00 · 2026-05-14 15:09:32 +08:00
parent 74c8e8f7e4
commit 8324b133fb
11 changed files with 64 additions and 15 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@
 ### Features

 - feat: |Frontend| 将邮箱地址凭证弹窗升级为“地址凭证与连接方式”，复用普通用户与 admin 创建邮箱结果弹窗；支持通过 `ENABLE_AGENT_EMAIL_INFO` 展示 AI Agent 接入信息，并通过 `SMTP_IMAP_PROXY_CONFIG` 展示 SMTP/IMAP 客户端连接信息
+- docs: |随机子域名| 在前端“启用随机子域名”提示与 `subdomain` / `worker-vars` 文档（中英）中明确说明：要让 `name@<随机>.abc.com` 真正收到邮件，必须在基础域名 DNS 中为 `*` 子域添加通配 MX 记录，Email Routing 子域不继承父域配置（issue #1035）

 ### Bug Fixes

--- a/CHANGELOG_EN.md
+++ b/CHANGELOG_EN.md
@@ -11,6 +11,7 @@
 ### Features

 - feat: |Frontend| Upgrade the address credential dialog to "Address Credentials & Connection Methods" and reuse it for both normal users and admin-created addresses; support showing AI Agent access via `ENABLE_AGENT_EMAIL_INFO` and SMTP/IMAP client settings via `SMTP_IMAP_PROXY_CONFIG`
+- docs: |Random Subdomain| Clarify in the "Use Random Subdomain" frontend tip and the `subdomain` / `worker-vars` docs (zh & en) that receiving mail on `name@<random>.abc.com` requires a wildcard `*` MX record under the base domain in DNS, because Cloudflare Email Routing does not inherit the apex configuration onto subdomains (issue #1035)

 ### Bug Fixes

--- a/frontend/src/i18n/locales/source/de.ts
+++ b/frontend/src/i18n/locales/source/de.ts
@@ -577,8 +577,8 @@ export const deMessages = {
  "views.Admin.webhookSettings": "Webhook-Einstellungen",
  "views.admin.AiExtractSettings.disabledTip": "Wenn deaktiviert, verarbeitet die KI-Extraktion alle E-Mail-Adressen",
  "views.admin.AiExtractSettings.enableAllowListTip": "Wenn aktiviert, verarbeitet die KI-Extraktion nur E-Mails an Adressen auf der Freigabeliste",
-  "views.admin.CreateAccount.randomSubdomainTip": "Wenn aktiviert, verwendet die erstellte Adresse eine zufällige Subdomain. Subdomain-Adressen werden nur für den Empfang empfohlen.",
-  "views.common.Login.randomSubdomainTip": "Wenn aktiviert, verwendet die erstellte Adresse eine zufällige Subdomain. Subdomain-Adressen werden nur für den Empfang empfohlen.",
+  "views.admin.CreateAccount.randomSubdomainTip": "Wenn aktiviert, verwendet die erstellte Adresse eine zufällige Subdomain. Nur für den Empfang empfohlen. Erfordert einen Wildcard-MX-DNS-Eintrag auf der Basisdomain — siehe die Dokumentation zu zufälligen Subdomains.",
+  "views.common.Login.randomSubdomainTip": "Wenn aktiviert, verwendet die erstellte Adresse eine zufällige Subdomain. Nur für den Empfang empfohlen. Erfordert einen Wildcard-MX-DNS-Eintrag auf der Basisdomain — siehe die Dokumentation zu zufälligen Subdomains.",
  "views.admin.AiExtractSettings.allowListTip": "Der Platzhalter * passt auf beliebige Zeichen; z. B. passt *{'@'}example.com auf alle Adressen der Domain example.com",
  "views.Admin.workerconfig": "Worker-Konfiguration",
  "views.admin.AccountSettings.create_address_subdomain_match_env_locked": "Die Worker-Umgebungsvariable ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH ist derzeit false. Der gespeicherte Admin-Schalter kann geändert werden, wird aber erst wirksam, wenn die Umgebungsvariable aktiviert oder entfernt wird.",
--- a/frontend/src/i18n/locales/source/es.ts
+++ b/frontend/src/i18n/locales/source/es.ts
@@ -577,8 +577,8 @@ export const esMessages = {
  "views.Admin.webhookSettings": "Configuración de webhook",
  "views.admin.AiExtractSettings.disabledTip": "Si está desactivado, la extracción IA procesará todas las direcciones",
  "views.admin.AiExtractSettings.enableAllowListTip": "Si está activado, la extracción IA solo procesará correos enviados a direcciones permitidas",
-  "views.admin.CreateAccount.randomSubdomainTip": "Si está activado, la dirección creada usará un subdominio aleatorio. Se recomienda usarlo solo para recibir.",
-  "views.common.Login.randomSubdomainTip": "Si está activado, la dirección creada usará un subdominio aleatorio. Se recomienda usarlo solo para recibir.",
+  "views.admin.CreateAccount.randomSubdomainTip": "Si está activado, la dirección creada usará un subdominio aleatorio. Recomendado solo para recibir. Requiere un registro MX comodín en el DNS del dominio base — consulta la documentación de subdominios aleatorios.",
+  "views.common.Login.randomSubdomainTip": "Si está activado, la dirección creada usará un subdominio aleatorio. Recomendado solo para recibir. Requiere un registro MX comodín en el DNS del dominio base — consulta la documentación de subdominios aleatorios.",
  "views.admin.AiExtractSettings.allowListTip": "El comodín * coincide con cualquier carácter; p. ej., *{'@'}example.com coincide con todas las direcciones del dominio example.com",
  "views.Admin.workerconfig": "Configuración del Worker",
  "views.admin.AccountSettings.create_address_subdomain_match_env_locked": "La variable ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH está en false. Puedes guardar el interruptor, pero no tendrá efecto hasta habilitar o quitar la variable.",
--- a/frontend/src/i18n/locales/source/ja.ts
+++ b/frontend/src/i18n/locales/source/ja.ts
@@ -577,8 +577,8 @@ export const jaMessages = {
  "views.Admin.webhookSettings": "Webhook設定",
  "views.admin.AiExtractSettings.disabledTip": "無効時は AI 抽出がすべてのメールアドレスを処理します",
  "views.admin.AiExtractSettings.enableAllowListTip": "有効時は AI 抽出は許可リストのアドレス宛メールのみ処理します",
-  "views.admin.CreateAccount.randomSubdomainTip": "有効時は作成されるアドレスがランダムなサブドメインを使用します。サブドメインアドレスは受信専用として推奨されます。",
-  "views.common.Login.randomSubdomainTip": "有効時は作成されるアドレスがランダムなサブドメインを使用します。サブドメインアドレスは受信専用として推奨されます。",
+  "views.admin.CreateAccount.randomSubdomainTip": "有効時は作成されるアドレスがランダムなサブドメインを使用します。受信専用として推奨されます。ベースドメインの DNS にワイルドカード MX レコードの設定が必要です — ランダムサブドメインのドキュメントを参照してください。",
+  "views.common.Login.randomSubdomainTip": "有効時は作成されるアドレスがランダムなサブドメインを使用します。受信専用として推奨されます。ベースドメインの DNS にワイルドカード MX レコードの設定が必要です — ランダムサブドメインのドキュメントを参照してください。",
  "views.admin.AiExtractSettings.allowListTip": "ワイルドカード * は任意の文字に一致します。例: *{'@'}example.com は example.com ドメイン配下のすべてのアドレスに一致します",
  "views.Admin.workerconfig": "Worker設定",
  "views.admin.AccountSettings.create_address_subdomain_match_env_locked": "Worker 環境変数 ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH は現在 false です。管理画面のスイッチは保存できますが、env を有効化または削除するまで反映されません。",
--- a/frontend/src/i18n/locales/source/ptBR.ts
+++ b/frontend/src/i18n/locales/source/ptBR.ts
@@ -577,8 +577,8 @@ export const ptBRMessages = {
  "views.Admin.webhookSettings": "Configurações de webhook",
  "views.admin.AiExtractSettings.disabledTip": "Quando desativado, a extração por IA processará todos os endereços",
  "views.admin.AiExtractSettings.enableAllowListTip": "Quando ativado, a extração por IA só processará e-mails enviados aos endereços permitidos",
-  "views.admin.CreateAccount.randomSubdomainTip": "Quando ativado, o endereço criado usará um subdomínio aleatório. Endereços com subdomínio são recomendados apenas para recebimento.",
-  "views.common.Login.randomSubdomainTip": "Quando ativado, o endereço criado usará um subdomínio aleatório. Endereços com subdomínio são recomendados apenas para recebimento.",
+  "views.admin.CreateAccount.randomSubdomainTip": "Quando ativado, o endereço criado usará um subdomínio aleatório. Recomendado apenas para recebimento. Requer um registro MX curinga no DNS do domínio base — consulte a documentação de subdomínios aleatórios.",
+  "views.common.Login.randomSubdomainTip": "Quando ativado, o endereço criado usará um subdomínio aleatório. Recomendado apenas para recebimento. Requer um registro MX curinga no DNS do domínio base — consulte a documentação de subdomínios aleatórios.",
  "views.admin.AiExtractSettings.allowListTip": "O curinga * corresponde a quaisquer caracteres; ex.: *{'@'}example.com corresponde a todos os endereços do domínio example.com",
  "views.Admin.workerconfig": "Configuração do Worker",
  "views.admin.AccountSettings.create_address_subdomain_match_env_locked": "A variável ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH está em false. O botão salvo pode ser alterado, mas só terá efeito quando a variável for ativada ou removida.",
--- a/frontend/src/i18n/message-registry.ts
+++ b/frontend/src/i18n/message-registry.ts
@@ -2001,8 +2001,8 @@ export const MESSAGE_REGISTRY = {
      "zh": "打开即可自动登录邮箱的链接"
    },
    "randomSubdomainTip": {
-      "en": "When enabled, the created address will use a random subdomain. Subdomain addresses are recommended for receiving only.",
-      "zh": "启用后，创建出来的地址会自动挂在随机子域名下。子域名地址更建议仅用于收件。"
+      "en": "When enabled, the created address will use a random subdomain. Recommended for receiving only. Requires a wildcard MX DNS record on the base domain — see the random subdomain docs.",
+      "zh": "启用后，创建出来的地址会自动挂在随机子域名下，建议仅用于收件。需要在基础域名 DNS 中配置通配 MX 记录，详见随机子域名文档。"
    },
    "successTip": {
      "en": "Success Created",
@@ -2523,8 +2523,8 @@ export const MESSAGE_REGISTRY = {
      "zh": "请\"登录\"或点击 \"注册新邮箱\" 按钮来获取一个新的邮箱地址"
    },
    "randomSubdomainTip": {
-      "en": "When enabled, the created address will use a random subdomain. Subdomain addresses are recommended for receiving only.",
-      "zh": "启用后，创建出来的地址会自动挂在随机子域名下。子域名地址更建议仅用于收件。"
+      "en": "When enabled, the created address will use a random subdomain. Recommended for receiving only. Requires a wildcard MX DNS record on the base domain — see the random subdomain docs.",
+      "zh": "启用后，创建出来的地址会自动挂在随机子域名下，建议仅用于收件。需要在基础域名 DNS 中配置通配 MX 记录，详见随机子域名文档。"
    }
  },
  "views.admin.Webhook": {
--- a/vitepress-docs/docs/en/guide/feature/subdomain.md
+++ b/vitepress-docs/docs/en/guide/feature/subdomain.md
@@ -52,9 +52,30 @@ If you want to create an address under a specific subdomain such as `team.abc.co
 >
 > There is currently no backend switch that globally forces random subdomains; API calls that do
 > not pass `enableRandomSubdomain: true` will not randomize automatically.
+
+> [!IMPORTANT] A wildcard MX DNS record is required for random subdomains
+> The worker only generates addresses like `name@<random>.abc.com` — **whether mail actually
+> arrives depends entirely on DNS / Email Routing being configured for `*.abc.com`**, and
+> Cloudflare Email Routing does **not** propagate the base-domain configuration onto subdomains.
+> See Cloudflare's [Email Routing — Subdomains](https://developers.cloudflare.com/email-routing/setup/subdomains/)
+> documentation.
 >
-> It does not automatically create Cloudflare-side subdomain mail routes or DNS records for you,
-> so make sure the base-domain/subdomain routing is already available first.
+> There are two ways to make `*.abc.com` deliverable:
+>
+> 1. **DNS-only wildcard MX (simplest workaround)** — In your DNS, copy **every existing MX
+>    record on `abc.com`** to host `*`, preserving each record's **priority and target value**.
+>    This makes `*.abc.com` resolve to the same MX targets as the apex, so mail flows into the
+>    same Cloudflare Email Routing zone and is picked up by the apex Catch-all rule that points
+>    at the Worker. No extra Cloudflare-side action is needed.
+> 2. **Cloudflare dashboard "Add subdomain"** — Add the specific subdomain in the Email Routing
+>    dashboard and configure its DNS + Catch-all routing rule separately. This only covers the
+>    specific subdomain you add, so it is not suitable for arbitrary random subdomains.
+>
+> For random subdomain mailboxes, option **(1)** is the recommended path. Without it, the
+> random subdomain feature will appear to work in the UI but inbound mail will never reach the
+> Worker.
+>
+> Reference issue: [#1035](https://github.com/dreamhunter2333/cloudflare_temp_email/issues/1035)

 ## Let APIs Specify Subdomains Directly

--- a/vitepress-docs/docs/en/guide/worker-vars.md
+++ b/vitepress-docs/docs/en/guide/worker-vars.md
@@ -51,6 +51,15 @@
 > `RANDOM_SUBDOMAIN_DOMAINS` only controls automatic random subdomain generation during mailbox
 > creation. It does not create Cloudflare-side subdomain routing for you.
 >
+> To actually receive mail on addresses like `name@<random>.abc.com`, **you must add a wildcard
+> `*` MX record under the base domain in DNS** by copying the apex's existing MX records to
+> host `*` (preserving each record's priority and target). Cloudflare Email Routing does not
+> inherit the apex configuration onto subdomains — see the
+> [Cloudflare Email Routing — Subdomains](https://developers.cloudflare.com/email-routing/setup/subdomains/)
+> docs,
+> [#1035](https://github.com/dreamhunter2333/cloudflare_temp_email/issues/1035) and
+> [Configure Subdomain Email](/en/guide/feature/subdomain).
+>
 > Subdomain addresses are usually best used for receiving only; for sending, prefer the main
 > domain.
 >
--- a/vitepress-docs/docs/zh/guide/feature/subdomain.md
+++ b/vitepress-docs/docs/zh/guide/feature/subdomain.md
@@ -45,8 +45,18 @@ RANDOM_SUBDOMAIN_LENGTH = 8
 > 这个功能只是在“创建地址”时自动补一个随机二级域名。
 >
 > 当前没有“全局强制随机二级域名”的后端开关；未传 `enableRandomSubdomain: true` 的 API 调用不会自动随机。
+
+> [!IMPORTANT] 随机子域名需要 DNS 通配 MX 记录
+> 程序只负责生成 `name@<random>.abc.com` 这样的地址，**能不能收到邮件完全取决于 DNS / Email Routing 是否覆盖到 `*.abc.com`**；Cloudflare Email Routing 的子域名配置**不会**从基础域名继承。可参考 Cloudflare 的 [Email Routing — Subdomains](https://developers.cloudflare.com/email-routing/setup/subdomains/) 文档。
 >
-> 它不会自动帮你创建 Cloudflare 侧的子域名收件路由或 DNS 配置，请先确保基础域名/子域名路由本身已经可用。
+> 让 `*.abc.com` 可投递有两种做法：
+>
+> 1. **DNS 通配 MX 记录（最简方案）** — 在 `abc.com` 的 DNS 中，把基础域名上**现有的每一条 MX 记录**都复制一份到 `*` 主机名上，**保留每条记录的 priority 与 target**。这样 `*.abc.com` 会解析到与 apex 相同的 MX 目标，邮件流向同一个 Cloudflare Email Routing zone，并由 apex 的 Catch-all 规则交给 Worker，**Cloudflare 侧不需要额外配置**。
+> 2. **Cloudflare 控制台 “Add subdomain”** — 在 Email Routing 后台显式添加该子域名，并单独配置其 DNS 与 Catch-all 路由规则。这只覆盖你添加的那个具体子域名，不适合随机生成的任意子域名。
+>
+> 随机子域名场景下推荐使用 **方案 (1)**。如果不做这一步，随机子域名功能在前端看起来正常，但实际邮件不会进入 Worker。
+>
+> 参考 issue：[#1035](https://github.com/dreamhunter2333/cloudflare_temp_email/issues/1035)

 ## 允许 API 直接指定子域名

--- a/vitepress-docs/docs/zh/guide/worker-vars.md
+++ b/vitepress-docs/docs/zh/guide/worker-vars.md
@@ -51,6 +51,13 @@
 > `RANDOM_SUBDOMAIN_DOMAINS` 只负责“创建地址时自动补随机子域名”，不会自动帮你创建 Cloudflare
 > 侧的子域名路由。
 >
+> 要让 `name@<随机>.abc.com` 这种随机子域名地址真的能收到邮件，**必须在基础域名的 DNS 中为
+> `*` 子域添加通配 MX 记录**：把基础域名上现有的每一条 MX 记录都复制到 `*` 主机名上，
+> 并保留 priority 与 target；Email Routing 子域不继承父域配置，详见 Cloudflare 的
+> [Email Routing — Subdomains](https://developers.cloudflare.com/email-routing/setup/subdomains/)
+> 文档、[#1035](https://github.com/dreamhunter2333/cloudflare_temp_email/issues/1035) 与
+> [配置子域名邮箱](/zh/guide/feature/subdomain)。
+>
 > 子域名地址通常更适合收件；如果要发件，仍建议优先使用主域名。
 >
 > `ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH` 与随机子域名功能不同：它允许 API 调用方**直接指定**