From 46fbb4c099ceb02889200efe98ac2d52806efcc5 Mon Sep 17 00:00:00 2001 From: Dream Hunter Date: Sat, 25 Apr 2026 21:35:14 +0800 Subject: [PATCH] docs: clarify Email Routing setup order (#1006) docs: clarify email routing setup order --- CHANGELOG.md | 2 +- CHANGELOG_EN.md | 2 +- vitepress-docs/docs/en/guide/email-routing.md | 3 +-- vitepress-docs/docs/en/guide/quick-start.md | 2 +- vitepress-docs/docs/en/guide/worker-vars.md | 2 +- vitepress-docs/docs/zh/guide/email-routing.md | 5 ++--- vitepress-docs/docs/zh/guide/quick-start.md | 2 +- vitepress-docs/docs/zh/guide/worker-vars.md | 2 +- 8 files changed, 9 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ea1b6329..112dcbff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +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） +- docs: |文档| 在 `quick-start` / `worker-vars` / `email-routing` 三个入口文档（中英文）显式补充"域名是部署前提条件"提示，强调需先在 Cloudflare 启用 Email Routing 并下发邮件 DNS 记录、Worker 部署后再绑定 Catch-all，子域名需单独启用，避免用户在没有可用域名时直接开始部署却收不到邮件（issue #1004） ### Bug Fixes diff --git a/CHANGELOG_EN.md b/CHANGELOG_EN.md index 2b972fb9..8c6d4abd 100644 --- a/CHANGELOG_EN.md +++ b/CHANGELOG_EN.md @@ -14,7 +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) +- 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 email DNS records provisioned before deployment, the Catch-all rule must be bound after the Worker is deployed, and 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 diff --git a/vitepress-docs/docs/en/guide/email-routing.md b/vitepress-docs/docs/en/guide/email-routing.md index 643b1965..5e92857d 100644 --- a/vitepress-docs/docs/en/guide/email-routing.md +++ b/vitepress-docs/docs/en/guide/email-routing.md @@ -5,9 +5,8 @@ > > - 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. +> After the Worker is deployed, you must also configure a Catch-all routing rule that delivers mail to that Worker. Without completing both phases, **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. diff --git a/vitepress-docs/docs/en/guide/quick-start.md b/vitepress-docs/docs/en/guide/quick-start.md index f58b2327..d8b85db7 100644 --- a/vitepress-docs/docs/en/guide/quick-start.md +++ b/vitepress-docs/docs/en/guide/quick-start.md @@ -4,7 +4,7 @@ > [!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**. +> You must already own a domain (apex or subdomain) hosted on Cloudflare DNS, with Email Routing enabled and the corresponding email DNS records provisioned. After the Worker is deployed, bind a Catch-all rule to that Worker. Without both steps, **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/) diff --git a/vitepress-docs/docs/en/guide/worker-vars.md b/vitepress-docs/docs/en/guide/worker-vars.md index 5373c7d0..da4c6509 100644 --- a/vitepress-docs/docs/en/guide/worker-vars.md +++ b/vitepress-docs/docs/en/guide/worker-vars.md @@ -14,7 +14,7 @@ | `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. +> Every domain you put here (including `DEFAULT_DOMAINS`, `USER_ROLES.domains`, `RANDOM_SUBDOMAIN_DOMAINS` further below) **must already have Cloudflare Email Routing enabled and its email DNS records provisioned**. After the Worker is deployed, bind the domain's Catch-all rule to that Worker; otherwise inbound mail will never reach the Worker. > See [Cloudflare Email Routing](/en/guide/email-routing) for the setup steps. ## Console Related Variables diff --git a/vitepress-docs/docs/zh/guide/email-routing.md b/vitepress-docs/docs/zh/guide/email-routing.md index ab2c8e35..6e246fcd 100644 --- a/vitepress-docs/docs/zh/guide/email-routing.md +++ b/vitepress-docs/docs/zh/guide/email-routing.md @@ -1,13 +1,12 @@ # Cloudflare Email Routing > [!IMPORTANT] 域名是部署的前提条件 -> 本项目的收件能力**完全依赖** Cloudflare Email Routing。开始部署 Worker / Pages 之前，你必须先准备好域名并把 Email Routing 配通： +> 本项目的收件能力**完全依赖** Cloudflare Email Routing。开始部署 Worker / Pages 之前，你必须先准备好域名并完成 Email Routing 的基础配置： > > - 域名 DNS 已托管在 Cloudflare。 > - 已在 Cloudflare 控制台为该域名启用 Email Routing，并完成 `电子邮件 DNS 记录` 的下发。 -> - 已配置 Catch-all 路由规则，目标指向你部署的 Worker（部署完 Worker 之后才能选到）。 > -> 没有完成上述配置，即使 Worker / Pages 部署成功，也**收不到邮件、无法接收任何验证码**。 +> Worker 部署完成后，你还必须配置 Catch-all 路由规则，把邮件投递到这个 Worker。没有完成这两个阶段的配置，即使 Worker / Pages 部署成功，也**收不到邮件、无法接收任何验证码**。 1. 在 CF 控制台网页的对应域名的 `Email Routing` 下，配置 `电子邮件 DNS 记录`, 如果是多个域名，需要配置多个域名的 `电子邮件 DNS 记录` diff --git a/vitepress-docs/docs/zh/guide/quick-start.md b/vitepress-docs/docs/zh/guide/quick-start.md index 3e5448c0..0cc840c0 100644 --- a/vitepress-docs/docs/zh/guide/quick-start.md +++ b/vitepress-docs/docs/zh/guide/quick-start.md @@ -4,7 +4,7 @@ > [!IMPORTANT] 必须先准备一个域名 > 本项目依赖 Cloudflare Email Routing 接收邮件，**域名是部署前提条件**。 -> 你必须先准备一个域名（一级域名或子域名均可），并在 Cloudflare 中托管 DNS、配置 Email Routing 与对应的电子邮件 DNS 记录（至少包含 Catch-all 规则），否则将**无法接收邮件 / 无法完成验证码流程**。 +> 你必须先准备一个域名（一级域名或子域名均可），并在 Cloudflare 中托管 DNS、启用 Email Routing、完成对应的电子邮件 DNS 记录下发。Worker 部署完成后，再把 Catch-all 规则绑定到这个 Worker；两步缺一都会导致**无法接收邮件 / 无法完成验证码流程**。 > 详细配置见 [Cloudflare Email Routing](/zh/guide/email-routing)。 需要 `良好的网络环境` 和 `cloudflare 账号`， 打开 [cloudflare控制台](https://dash.cloudflare.com/) diff --git a/vitepress-docs/docs/zh/guide/worker-vars.md b/vitepress-docs/docs/zh/guide/worker-vars.md index 0c7c3e62..37755d31 100644 --- a/vitepress-docs/docs/zh/guide/worker-vars.md +++ b/vitepress-docs/docs/zh/guide/worker-vars.md @@ -14,7 +14,7 @@ | `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。 +> 这里填写的所有域名（包括下文「邮箱相关变量」里的 `DEFAULT_DOMAINS`、`USER_ROLES.domains`、`RANDOM_SUBDOMAIN_DOMAINS` 等）必须是你**已经在 Cloudflare Email Routing 中启用并完成邮件 DNS 记录下发**的域名。Worker 部署完成后，还需要把该域名的 Catch-all 规则绑定到这个 Worker，否则邮件无法投递到 Worker。 > 配置步骤见 [Cloudflare Email Routing](/zh/guide/email-routing)。 ## 后台相关变量