diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ef5b808 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +node_modules/ +.wrangler/ +dist/ diff --git a/LICENSE b/LICENSE index 261eeb9..c662c40 100644 --- a/LICENSE +++ b/LICENSE @@ -30,7 +30,7 @@ "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, - and conversions to other media types. + and conversions to other media formats. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a @@ -122,7 +122,7 @@ You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or + for use, reproduction, or distribution of your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. @@ -155,7 +155,7 @@ unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a + incidental, or exemplary damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all @@ -175,17 +175,6 @@ END OF TERMS AND CONDITIONS - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); diff --git a/README.md b/README.md new file mode 100644 index 0000000..42526c9 --- /dev/null +++ b/README.md @@ -0,0 +1,138 @@ +# mail-worker + +一個極簡的 Cloudflare Worker，用於接收域名郵件並提供 HTTP API 讀取。 + +無需資料庫、無需前端、無需 JWT，部署後即可通過 API 取得最新郵件內容。 + +## 特性 + +- 📨 通過 Cloudflare Email Routing 接收郵件 +- 🗄️ 使用 KV 儲存，最多保留 50 封 +- 🔑 API Key 鑑權 +- 🌐 支持多個自定義域名（域名需托管在 Cloudflare） +- 📦 僅依賴 `postal-mime`，無其他依賴 + +## 前置條件 + +- 域名已托管在 Cloudflare +- 已啟用 Cloudflare Email Routing + +## 部署 + +### 方式一：Cloudflare 一鍵部署 + +[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/OWNER/REPO) + +點擊按鈕後，Cloudflare 會自動 Fork 此 repo 並完成代碼部署。 + +部署完成後，還需手動完成以下兩步： + +**1. 建立 KV Namespace 並綁定** + +```bash +wrangler kv:namespace create MAIL_KV +``` + +複製輸出的 `id`，前往 Cloudflare 控制台 → Workers & Pages → 你的 worker → Settings → Bindings → 新增 KV Namespace，名稱填 `MAIL_KV`，選擇剛建立的 namespace。 + +**2. 設定環境變數** + +Cloudflare 控制台 → Workers & Pages → 你的 worker → Settings → Variables → 新增： + +| 變數名 | 值 | +|---|---| +| `AUTH_KEY` | 自訂一個密碼 | + +--- + +### 方式二：本地 CLI 部署 + +**1. 安裝依賴** + +```bash +npm install wrangler postal-mime +``` + +**2. 建立 KV Namespace** + +```bash +wrangler kv:namespace create MAIL_KV +``` + +複製輸出的 `id`，填入 `wrangler.toml`。 + +**3. 配置 `wrangler.toml`** + +```toml +[vars] +AUTH_KEY = "換成你的密碼" + +[[kv_namespaces]] +binding = "MAIL_KV" +id = "貼上剛才的 KV ID" +``` + +**4. 部署** + +```bash +wrangler deploy +``` + +**5. 設定 Email Routing** + +Cloudflare 控制台 → Email → Email Routing → Catch-all rule → Action: Send to Worker → 選擇 `mail-worker` + +## 自定義域名（可選） + +> 域名必須已托管在 Cloudflare，無需手動建立 DNS 記錄，Cloudflare 會自動處理並簽發 SSL。 + +在 `wrangler.toml` 中取消注釋並填入你的子域名，支持多個： + +```toml +[[routes]] +pattern = "mail.domain-a.com" +custom_domain = true + +[[routes]] +pattern = "mail.domain-b.com" +custom_domain = true +``` + +重新部署後即可通過自定義域名訪問 API。多個域名收到的郵件共用同一個 inbox，`to` 欄位可用於區分來源域名。 + +## API + +所有請求需帶上 Header：`X-Auth-Key: 你的密碼` + +| 方法 | 路徑 | 說明 | +|---|---|---| +| GET | `/latest` | 取得最新一封完整郵件 | +| GET | `/mails?limit=10` | 取得最近 N 封郵件列表（不含正文） | +| GET | `/mail/:id` | 取得單封完整郵件（含 html/text） | +| DELETE | `/mails` | 清空收件匣 | + +**範例** + +```bash +# 使用自定義域名取得最新郵件 +curl https://mail.yourdomain.com/latest \ + -H "X-Auth-Key: 你的密碼" + +# 回應範例 +{ + "id": "uuid-xxxx", + "receivedAt": "2025-03-22T10:00:00.000Z", + "from": "[email protected]", + "to": "[email protected]", + "subject": "驗證碼：123456", + "text": "你的驗證碼是 123456", + "html": "

你的驗證碼是 123456

", + "attachments": [ + { "filename": "report.pdf", "mimeType": "application/pdf", "size": 102400 } + ] +} +``` + +## License + +Apache License 2.0 diff --git a/package.json b/package.json new file mode 100644 index 0000000..f7fa58a --- /dev/null +++ b/package.json @@ -0,0 +1,16 @@ +{ + "name": "mail-worker", + "version": "1.0.0", + "description": "Minimal Cloudflare Worker for receiving and reading emails via API", + "main": "src/worker.js", + "scripts": { + "deploy": "wrangler deploy", + "dev": "wrangler dev" + }, + "dependencies": { + "postal-mime": "^2.2.9" + }, + "devDependencies": { + "wrangler": "^3.0.0" + } +} diff --git a/wrangler.toml b/wrangler.toml new file mode 100644 index 0000000..a2ad126 --- /dev/null +++ b/wrangler.toml @@ -0,0 +1,19 @@ +name = "mail-worker" +main = "src/worker.js" +compatibility_date = "2024-09-23" +compatibility_flags = ["nodejs_compat"] + +# ── 自定義域名（域名需已托管在 Cloudflare）──────────────────────── +# Cloudflare 會自動建立 DNS 記錄並簽發 SSL，無需手動操作 +# 取消下面兩行注釋並填入你的域名即可 +# [[routes]] +# pattern = "mail.yourdomain.com" +# custom_domain = true +# ───────────────────────────────────────────────────────────────── + +[vars] +AUTH_KEY = "換成你的密碼" + +[[kv_namespaces]] +binding = "MAIL_KV" +id = "貼上你的 KV Namespace ID"