docs: add SMTP sending tutorial - #1059
Open
dashitongzhi wants to merge 3 commits into
Open
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (8)
✅ Files skipped from review due to trivial changes (7)
📝 WalkthroughWalkthrough中英文文档补充了 SMTP 配置规则、Cloudflare 配置步骤、服务商示例、发送接口 curl 示例和常见问题排查，并同步更新了 changelog 条目。 ChangesSMTP 邮件发送指南
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds a step-by-step SMTP sending tutorial to help users configure outbound email for Cloudflare Temp Email, complementing the existing reference docs and addressing common setup questions (ref: #609).
Changes:
- Introduces a new SMTP-focused walkthrough for setting
SMTP_CONFIGin Cloudflare Workers. - Adds provider-specific configuration recipes (Gmail, Outlook/M365, custom SMTP).
- Documents common errors and includes curl examples for the send APIs.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| }' | ||
| ``` | ||
|
|
||
| ### 7.3 Check what is left in the outbox |
Comment on lines
+135
to
+138
| > [!WARNING] | ||
| > Google Workspace admins can disable App Passwords org-wide. If | ||
| > `530-5.5.1 Authentication required` keeps appearing, ask your admin to | ||
| > allow less-secure-app access or switch to Resend. |
Comment on lines
+209
to
+210
| | `Error: connect ECONNREFUSED / ETIMEDOUT` | Cloudflare IPs blocked by the relay, or wrong port/secure flag | Use port 465 with `secure: true`; if your ISP relays do not allow Cloudflare, switch to Resend/Mailgun | | ||
| | `Error: self signed certificate` | `secure: true` against a server whose TLS cert isn't trusted | Fix the cert, or set `secure: false` with port 587 + STARTTLS | |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/SMTP_SENDING.md (1)
70-105: 补充说明 SMTP_CONFIG 顶层键的精确匹配契约及回退条件
getDomainMapValue会对SMTP_CONFIG的顶层 key 和mailDomain都做normalizeDomain（trim + toLowerCase），然后用===做精确相等匹配；不做子域/后缀匹配（除非 key 本身就是该子域）。send_mail_api.ts里只有当匹配到的smtpConfig存在时才会走 SMTP；否则会依次走 resend / sendMailBinding（或已验证地址列表），若这些也都未启用最终会抛错而非永远“静默禁用”。建议在 3.
SMTP_CONFIG章节正文再把“归一化后精确相等 + 不匹配则跳过 SMTP（可能最终报错）”明确写出来。🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/SMTP_SENDING.md` around lines 70 - 105, Clarify in the "3. The `SMTP_CONFIG` JSON" section that getDomainMapValue normalizes both the SMTP_CONFIG top-level keys and the mailDomain using normalizeDomain (trim + toLowerCase) and then requires exact equality (===) — no implicit subdomain/suffix matching — and explicitly state that send_mail_api.ts will only use SMTP when a matching smtpConfig exists; otherwise it falls back to resend / sendMailBinding (or verified-address list) and may ultimately throw an error if no channel is available.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/SMTP_SENDING.md`:
- Around line 70-105: Clarify in the "3. The `SMTP_CONFIG` JSON" section that
getDomainMapValue normalizes both the SMTP_CONFIG top-level keys and the
mailDomain using normalizeDomain (trim + toLowerCase) and then requires exact
equality (===) — no implicit subdomain/suffix matching — and explicitly state
that send_mail_api.ts will only use SMTP when a matching smtpConfig exists;
otherwise it falls back to resend / sendMailBinding (or verified-address list)
and may ultimately throw an error if no channel is available.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 4e6d672d-cfcc-4ec7-b2e1-473711d93e1a
📒 Files selected for processing (1)
docs/SMTP_SENDING.md
dreamhunter2333
requested changes
Jun 13, 2026
dreamhunter2333
left a comment
dreamhunter2333
left a comment
Owner
There was a problem hiding this comment.
开发者 Review / Developer review
谢谢补充 SMTP 发送教程。不过这份文档现在不能直接合并，主要原因是位置和语言结构不符合项目文档体系。
需要调整：
- 请不要新增根目录
docs/SMTP_SENDING.md。当前项目文档站使用 VitePress，实际文档位于vitepress-docs/docs/{zh,en}/...，根目录docs/不会进入文档站导航，也不会被现有文档部署流程正确展示。 - 请把内容拆到现有正确位置，并保持中英文双语：
- SMTP 配置、Cloudflare Dashboard / CLI secrets、provider recipes：放到
vitepress-docs/docs/zh/guide/config-send-mail.md和vitepress-docs/docs/en/guide/config-send-mail.md - HTTP
/api/send_mail//external/api/send_mailcurl 示例：放到vitepress-docs/docs/zh/guide/feature/send-mail-api.md和vitepress-docs/docs/en/guide/feature/send-mail-api.md - 常见错误排查：补充到
vitepress-docs/docs/zh/guide/common-issues.md和vitepress-docs/docs/en/guide/common-issues.md
- SMTP 配置、Cloudflare Dashboard / CLI secrets、provider recipes：放到
- 如果你想保留一篇独立的 beginner tutorial，也需要创建成 VitePress 双语页面，例如
vitepress-docs/docs/zh/guide/...+vitepress-docs/docs/en/guide/...，并同步更新vitepress-docs/docs/.vitepress/zh.ts和vitepress-docs/docs/.vitepress/en.ts的 sidebar。 - 请顺手补充
CHANGELOG.md和CHANGELOG_EN.md当前v1.10.0(main)下的 docs entry。
English:
Thanks for adding the SMTP sending guide. This cannot be merged as-is because the file is outside the project documentation structure and only adds an English page.
Requested changes:
- Please do not add
docs/SMTP_SENDING.mdat the repository root. This project serves docs from VitePress undervitepress-docs/docs/{zh,en}/...; the rootdocs/file will not appear in the docs site/navigation or the current deployment flow. - Please move/split the content into the existing bilingual VitePress pages:
- SMTP configuration, Dashboard / CLI secrets, and provider recipes:
vitepress-docs/docs/zh/guide/config-send-mail.mdandvitepress-docs/docs/en/guide/config-send-mail.md - HTTP
/api/send_mail//external/api/send_mailcurl examples:vitepress-docs/docs/zh/guide/feature/send-mail-api.mdandvitepress-docs/docs/en/guide/feature/send-mail-api.md - Common errors and troubleshooting:
vitepress-docs/docs/zh/guide/common-issues.mdandvitepress-docs/docs/en/guide/common-issues.md
- SMTP configuration, Dashboard / CLI secrets, and provider recipes:
- If you prefer a standalone beginner tutorial, it still needs paired VitePress pages under
vitepress-docs/docs/zh/guide/...andvitepress-docs/docs/en/guide/..., plus matching sidebar entries invitepress-docs/docs/.vitepress/zh.tsandvitepress-docs/docs/.vitepress/en.ts. - Please also add a docs entry to the current
v1.10.0(main)sections in bothCHANGELOG.mdandCHANGELOG_EN.md.
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@vitepress-docs/docs/en/guide/config-send-mail.md`:
- Line 83: The fallback order description is inaccurate: the verified address
list is a short-circuit check, not a late fallback. Update the text in the docs
section that describes the mail-routing flow so it says the verified address
list is checked first and, if matched, the request goes through SEND_MAIL
immediately; only when it does not match should the logic continue to other
available channels such as SMTP, Resend, or the binding fallback. Keep the
wording aligned with the routing behavior described alongside SMTP_CONFIG and
SEND_MAIL.
In `@vitepress-docs/docs/zh/guide/config-send-mail.md`:
- Line 83: 文档中的回退顺序描述不准确，应先在相关说明里修正“已验证地址列表”的位置和行为：它不是最后兜底，而是优先短路判断，命中后会直接走
SEND_MAIL。请在该段落中结合 SMTP_CONFIG、smtpConfig 和 SEND_MAIL 的描述，改成“已验证地址列表优先判断；未命中后再按
SMTP、Resend、SEND_MAIL binding 等可用通道继续”，避免误导排障。
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8db8483a-565c-4c04-bca3-8a3f837753eb
📒 Files selected for processing (8)
CHANGELOG.mdCHANGELOG_EN.mdvitepress-docs/docs/en/guide/common-issues.mdvitepress-docs/docs/en/guide/config-send-mail.mdvitepress-docs/docs/en/guide/feature/send-mail-api.mdvitepress-docs/docs/zh/guide/common-issues.mdvitepress-docs/docs/zh/guide/config-send-mail.mdvitepress-docs/docs/zh/guide/feature/send-mail-api.md
✅ Files skipped from review due to trivial changes (6)
- CHANGELOG_EN.md
- vitepress-docs/docs/zh/guide/common-issues.md
- vitepress-docs/docs/zh/guide/feature/send-mail-api.md
- vitepress-docs/docs/en/guide/feature/send-mail-api.md
- vitepress-docs/docs/en/guide/common-issues.md
- CHANGELOG.md
- Add docs/SMTP_SENDING.md with step-by-step SMTP configuration, app passwords, supported providers (Gmail / Outlook / custom), common errors and fixes, and 3 curl examples for sending mail via the Cloudflare email worker API - References dreamhunter2333#609
dashitongzhi
force-pushed
the
docs/smtp-sending-tutorial-20260613090754
branch
from
June 25, 2026 03:59
528db29 to
76dc332
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/SMTP_SENDING.mdguide covering SMTP send configuration, app passwords, supported providers (Gmail, Outlook, custom), common errors and fixes, and 3 workingcurlexamples for sending mail via the Cloudflare email worker APIMotivation
Closes #609 — community requested a follow-up to the existing 小白版教程 (beginner tutorial) covering outgoing mail/SMTP.
Test Plan
File Added
docs/SMTP_SENDING.mdSummary by CodeRabbit
SMTP_CONFIG密钥配置位置说明与完整填入部署步骤。SMTP_CONFIG与发件域名的归一化后精确相等匹配规则（不支持子域/后缀），以及未命中后的通道回退顺序与更多 Provider 示例（Gmail/Outlook/自托管）。curl调试示例，并扩展常见故障排查（认证/连接/证书/DNS/垃圾箱）。