diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f9e6ff..ea1b632 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/CHANGELOG_EN.md b/CHANGELOG_EN.md index f1c795f..2b972fb 100644 --- a/CHANGELOG_EN.md +++ b/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 diff --git a/vitepress-docs/docs/en/guide/email-routing.md b/vitepress-docs/docs/en/guide/email-routing.md index ef7a576..643b196 100644 --- a/vitepress-docs/docs/en/guide/email-routing.md +++ b/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**. diff --git a/vitepress-docs/docs/en/guide/quick-start.md b/vitepress-docs/docs/en/guide/quick-start.md index c0a9f6a..f58b232 100644 --- a/vitepress-docs/docs/en/guide/quick-start.md +++ b/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: diff --git a/vitepress-docs/docs/en/guide/worker-vars.md b/vitepress-docs/docs/en/guide/worker-vars.md index 1704f69..5373c7d 100644 --- a/vitepress-docs/docs/en/guide/worker-vars.md +++ b/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 | diff --git a/vitepress-docs/docs/zh/guide/email-routing.md b/vitepress-docs/docs/zh/guide/email-routing.md index aa5366f..ab2c8e3 100644 --- a/vitepress-docs/docs/zh/guide/email-routing.md +++ b/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 配置，未单独启用的子域名邮件将**无法投递**。 diff --git a/vitepress-docs/docs/zh/guide/quick-start.md b/vitepress-docs/docs/zh/guide/quick-start.md index f6ed57c..3e5448c 100644 --- a/vitepress-docs/docs/zh/guide/quick-start.md +++ b/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/) 请选择下面三种方式之一进行部署 diff --git a/vitepress-docs/docs/zh/guide/worker-vars.md b/vitepress-docs/docs/zh/guide/worker-vars.md index 6b4ede3..0c7c3e6 100644 --- a/vitepress-docs/docs/zh/guide/worker-vars.md +++ b/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)。 + ## 后台相关变量 | 变量名 | 类型 | 说明 | 示例 |