docs: highlight that a domain is a prerequisite for deployment (#1005)

In quick-start / worker-vars / email-routing (zh + en), explicitly
call out that a Cloudflare-hosted domain with Email Routing + Catch-all
must be set up before deploying, and that subdomains do not inherit
the parent domain's Email Routing. Closes #1004.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -14,6 +14,7 @@
 - feat: |API| 新增服务端解析邮件接口 `/api/parsed_mails` 与 `/api/parsed_mail/:id`，直接返回 `sender` / `subject` / `text` / `html` / `attachments` 元信息（复用 `commonParseMail`），AI agent 侧不再需要引入 MIME 解析器
 - feat: |Skill| 新增仓库内置只读 skill `cf-temp-mail-agent-mail`（`skills/cf-temp-mail-agent-mail/`），让 OpenClaw / Codex / Cursor 等 AI agent 凭用户提供的 Address JWT + API 地址读取邮箱、轮询验证码，绕开创建邮箱时的 Turnstile 人机验证；可通过 `npx degit dreamhunter2333/cloudflare_temp_email/skills/cf-temp-mail-agent-mail` 安装
 - docs: |文档| 新增"AI Agent 使用邮箱"文档（`guide/feature/agent-email`），说明 `parsed_mail` API 用法，并在 parsed API 不可用时给出对齐前端的 `mail-parser-wasm` + `postal-mime` 本地解析回退方案
+- docs: |文档| 在 `quick-start` / `worker-vars` / `email-routing` 三个入口文档（中英文）显式补充"域名是部署前提条件"提示，强调需先在 Cloudflare 启用 Email Routing 并配置 Catch-all、子域名需单独启用，避免用户在没有可用域名时直接开始部署却收不到邮件（issue #1004）
 
 ### Bug Fixes
 

CHANGELOG_EN.md

@@ -14,6 +14,7 @@
 - feat: |API| Add server-side parsed-mail endpoints `/api/parsed_mails` and `/api/parsed_mail/:id` that return `sender` / `subject` / `text` / `html` / `attachments` metadata directly (reuses `commonParseMail`), so AI agents no longer need a client-side MIME parser
 - feat: |Skill| Bundle a read-only skill `cf-temp-mail-agent-mail` (`skills/cf-temp-mail-agent-mail/`) so AI agents like OpenClaw / Codex / Cursor can consume a mailbox with a user-supplied Address JWT + API base URL — list mails, poll verification codes, etc. — sidestepping the Turnstile challenge required to create a mailbox. Install via `npx degit dreamhunter2333/cloudflare_temp_email/skills/cf-temp-mail-agent-mail`
 - docs: |Docs| Add "AI Agent Mailbox Usage" doc (`guide/feature/agent-email`) covering the `parsed_mail` API and a local-parse fallback using `mail-parser-wasm` + `postal-mime` (mirrors the frontend) when parsed endpoints are unavailable
+- docs: |Docs| Make "a domain is a hard prerequisite" explicit at the top of `quick-start`, `worker-vars`, and `email-routing` (zh + en), spelling out that Cloudflare Email Routing must be enabled with a Catch-all rule and that subdomains do not inherit the parent domain's Email Routing — so users no longer start deploying without a usable domain and end up unable to receive mail (issue #1004)
 
 ### Bug Fixes
 

vitepress-docs/docs/en/guide/email-routing.md

@@ -1,5 +1,14 @@
 # Cloudflare Email Routing
 
+> [!IMPORTANT] A domain is a hard prerequisite for deployment
+> Mail reception in this project is **entirely dependent on** Cloudflare Email Routing. Before deploying Worker / Pages, you must already have:
+>
+> - A domain whose DNS is hosted on Cloudflare.
+> - Email Routing enabled on that domain in the Cloudflare dashboard, with the `Email DNS records` provisioned.
+> - A Catch-all routing rule that delivers mail to your deployed Worker (this can only be selected after the Worker is deployed).
+>
+> Without all of the above, **no inbound mail and no verification code will ever be received**, even if the Worker / Pages deployment itself succeeds.
+
 1. In the CF console for the corresponding domain under `Email Routing`, configure the `Email DNS records`. If there are multiple domains, you need to configure `Email DNS records` for each domain.
 
 2. Before binding an email address to your Worker, you need to enable email routing and have at least one verified email address (destination address).
@@ -9,4 +18,4 @@
 ![email](/readme_assets/email.png)
 
 > [!WARNING] Subdomains must be configured separately
-> If you want to receive mail on a **subdomain** (e.g. `mail.example.com`), you must enable `Email Routing` on **that subdomain** in the CF dashboard and configure its email DNS records and Catch-all rule separately. Enabling Email Routing only on the apex domain **does not cover subdomains**.
+> If you want to receive mail on a **subdomain** (e.g. `mail.example.com`), you must enable `Email Routing` on **that subdomain** in the CF dashboard and configure its email DNS records and Catch-all rule separately. Enabling Email Routing only on the apex domain **does not cover subdomains**, and a subdomain **does not inherit** its parent domain's Email Routing configuration — mail to a subdomain that has not been individually enabled will **fail to deliver**.

vitepress-docs/docs/en/guide/quick-start.md

@@ -2,6 +2,11 @@
 
 ## Before You Begin
 
+> [!IMPORTANT] A domain is required first
+> This project relies on Cloudflare Email Routing to receive emails, so **a domain is a hard prerequisite for deployment**.
+> You must already own a domain (apex or subdomain) hosted on Cloudflare DNS, with Email Routing enabled and the corresponding email DNS records (including a Catch-all rule) configured. Without it, **mail will not be received and verification flows will fail**.
+> See [Cloudflare Email Routing](/en/guide/email-routing) for the full setup.
+
 You need a `good network environment` and a `Cloudflare account`. Open the [Cloudflare Dashboard](https://dash.cloudflare.com/)
 
 Please choose one of the three deployment methods below:

vitepress-docs/docs/en/guide/worker-vars.md

@@ -13,6 +13,10 @@
 | `ENABLE_USER_CREATE_EMAIL` | Text/JSON   | Whether to allow users to create mailboxes, disabled if not configured | `true`                               |
 | `ENABLE_USER_DELETE_EMAIL` | Text/JSON   | Whether to allow users to delete emails, disabled if not configured    | `true`                               |
 
+> [!IMPORTANT] `DOMAINS` and `DEFAULT_DOMAINS` must already be set up in Cloudflare
+> Every domain you put here (including `DEFAULT_DOMAINS`, `USER_ROLES.domains`, `RANDOM_SUBDOMAIN_DOMAINS` further below) **must already have Cloudflare Email Routing enabled with a Catch-all rule pointing at the Worker**, otherwise inbound mail will never reach the Worker.
+> See [Cloudflare Email Routing](/en/guide/email-routing) for the setup steps.
+
 ## Console Related Variables
 
 | Variable Name                  | Type      | Description                                             | Example          |

vitepress-docs/docs/zh/guide/email-routing.md

@@ -1,5 +1,14 @@
 # Cloudflare Email Routing
 
+> [!IMPORTANT] 域名是部署的前提条件
+> 本项目的收件能力**完全依赖** Cloudflare Email Routing。开始部署 Worker / Pages 之前，你必须先准备好域名并把 Email Routing 配通：
+>
+> - 域名 DNS 已托管在 Cloudflare。
+> - 已在 Cloudflare 控制台为该域名启用 Email Routing，并完成 `电子邮件 DNS 记录` 的下发。
+> - 已配置 Catch-all 路由规则，目标指向你部署的 Worker（部署完 Worker 之后才能选到）。
+>
+> 没有完成上述配置，即使 Worker / Pages 部署成功，也**收不到邮件、无法接收任何验证码**。
+
 1. 在 CF 控制台网页的对应域名的 `Email Routing` 下，配置 `电子邮件 DNS 记录`, 如果是多个域名，需要配置多个域名的 `电子邮件 DNS 记录`
 
 2. 在将电子邮件地址绑定到您的 Worker 之前，您需要启用电子邮件路由并拥有至少一个经过验证的电子邮件地址(目标地址)。
@@ -9,4 +18,4 @@
 ![email](/readme_assets/email.png)
 
 > [!WARNING] 子域需要单独配置
-> 如果你要用**子域名**（如 `mail.example.com`）收信，必须在 CF 控制台里对 **该子域** 单独启用 `Email Routing`，并配置邮件 DNS 记录与 Catch-all 规则。仅在一级域名上开启 Email Routing **不会自动覆盖子域名**。
+> 如果你要用**子域名**（如 `mail.example.com`）收信，必须在 CF 控制台里对 **该子域** 单独启用 `Email Routing`，并配置邮件 DNS 记录与 Catch-all 规则。仅在一级域名上开启 Email Routing **不会自动覆盖子域名**，子域名也**不会自动继承**父域名的 Email Routing 配置，未单独启用的子域名邮件将**无法投递**。

vitepress-docs/docs/zh/guide/quick-start.md

@@ -2,6 +2,11 @@
 
 ## 开始之前
 
+> [!IMPORTANT] 必须先准备一个域名
+> 本项目依赖 Cloudflare Email Routing 接收邮件，**域名是部署前提条件**。
+> 你必须先准备一个域名（一级域名或子域名均可），并在 Cloudflare 中托管 DNS、配置 Email Routing 与对应的电子邮件 DNS 记录（至少包含 Catch-all 规则），否则将**无法接收邮件 / 无法完成验证码流程**。
+> 详细配置见 [Cloudflare Email Routing](/zh/guide/email-routing)。
+
 需要 `良好的网络环境` 和 `cloudflare 账号`， 打开 [cloudflare控制台](https://dash.cloudflare.com/)
 
 请选择下面三种方式之一进行部署

vitepress-docs/docs/zh/guide/worker-vars.md

@@ -13,6 +13,10 @@
 | `ENABLE_USER_CREATE_EMAIL` | 文本/JSON   | 是否允许用户创建邮箱, 不配置则不允许       | `true`                               |
 | `ENABLE_USER_DELETE_EMAIL` | 文本/JSON   | 是否允许用户删除邮件, 不配置则不允许       | `true`                               |
 
+> [!IMPORTANT] DOMAINS 与 DEFAULT_DOMAINS 必须先在 Cloudflare 配置好
+> 这里填写的所有域名（包括下文「邮箱相关变量」里的 `DEFAULT_DOMAINS`、`USER_ROLES.domains`、`RANDOM_SUBDOMAIN_DOMAINS` 等）必须是你**已经在 Cloudflare Email Routing 中启用并配置过 Catch-all 规则**的域名，否则邮件无法投递到 Worker。
+> 配置步骤见 [Cloudflare Email Routing](/zh/guide/email-routing)。
+
 ## 后台相关变量
 
 | 变量名                         | 类型      | 说明                                 | 示例             |