benchou-mail API

收 *@benchou0401.cc 的所有信件、以及 iOS 捷徑轉送的簡訊，用 HTTP API 讀取。

Base URL：https://api.benchou0401.cc　·　目前 不需要 token（在 /health 可看 auth.enabled）

🚀 iOS 捷徑：3 分鐘設好一支手機

每支手機各設一次。填 owner（例如「小明」）就能區分是誰的簡訊，不會混在一起。

Step-by-step

  1. 打開「捷徑」App，底下切到「自動化」分頁
  2. 右上角「+」→ 選「訊息」
  3. 設定觸發條件：
  4. 加動作：搜尋「取得網址內容」→ 點加入
  5. URL 貼上：https://api.benchou0401.cc/sms
  6. 點動作下方的「顯示更多」展開，把「方法」改成 POST
  7. 「請求內文」選 JSON，然後「新增欄位」→「文字」，加 3 個欄位：
    owner
    這支手機的代號，例如 小明（每支手機取不同名字）
    content
    值那格點進去 → 變數選單 → 選「捷徑輸入」→ 再點一次它 → 改成「內容」
    tag
    這組自動化的關鍵字，例如 驗證碼
  8. 右上角「完成」儲存
  9. 測試：請人傳一則含關鍵字的簡訊給你，然後在瀏覽器打開： 
    https://api.benchou0401.cc/sms/latest?owner=小明
    看到內容跟 code（自動抽出的驗證碼）就成功了 🎉
Tip：要幫別人設同樣的自動化？直接把上面的步驟截圖傳給他，把 owner 改成他的名字就好。
常見坑：

📱 簡訊 /sms

路徑說明
POST /sms 寫入一則簡訊。JSON：owner（必填）、content（必填）、sender、tag、received_at（存為 device_time）
GET /sms 列出簡訊（新到舊）
GET /sms/latest 最新一則（單筆物件）；帶 ?latest=N 回最新 N 筆陣列
GET /sms/owners 列出所有 owner + 筆數 + 最後收到時間
GET /sms/:id 取得單則
DEL /sms/:id 刪除單則 🔒（設 token 時）
DEL /sms?older_than_days=7[&owner=X] 清除 N 天前的簡訊（可只清某人的）🔒

查詢參數（/sms 和 /sms/latest 都能用）

參數說明範例
latest回最新 N 筆（1–200，預設 50）
也接受 ?n= 或 ?limit=		?latest=10
owner只看某人的簡訊?owner=小明
tag依 tag 過濾?tag=驗證碼
sender依寄件人模糊比對?sender=+886
q內文關鍵字?q=蝦皮
has_code=1只看能抽出 code 的?has_code=1
since某毫秒時間戳之後?since=1789430000000
offset分頁位移?offset=50

範例

# 小明最新一則驗證碼
curl "https://api.benchou0401.cc/sms/latest?owner=小明&tag=驗證碼"

# 小明最新 5 則（回陣列）
curl "https://api.benchou0401.cc/sms/latest?owner=小明&latest=5"

# 所有人最新 10 則
curl "https://api.benchou0401.cc/sms?latest=10"

# 看有哪些 owner 送過簡訊
curl "https://api.benchou0401.cc/sms/owners"

# 手動 POST 一則（測試用）
curl -X POST "https://api.benchou0401.cc/sms" \
  -H "Content-Type: application/json" \
  -d '{"owner":"小明","content":"【XX銀行】您的驗證碼為 123456","tag":"驗證碼"}'

✉️ 信件 /emails

路徑說明
GET /emails 列出信件（新到舊）
GET /emails/:id 取得單封
DEL /emails/:id 刪除單封 🔒

回應多帶 code（自動抽出的驗證碼）跟 links（信中所有 URL）。

查詢參數

參數說明範例
latest回最新 N 封（1–200，預設 50）?latest=10
to依收件人 local part（xxx@ 前面那段）?to=signup
from依寄件人模糊比對?from=github
since某毫秒時間戳之後?since=1789430000000
offset分頁位移?offset=50

範例

# 寄到 signup@benchou0401.cc 的最新 3 封
curl "https://api.benchou0401.cc/emails?to=signup&latest=3"

# 所有信件最新 20 封
curl "https://api.benchou0401.cc/emails?latest=20"

🔧 邏輯細節

去重：同一 owner 90 秒內相同內文只存一筆，第二次回 duplicate: true；若帶不同 tag 會合併成 驗證碼,銀行。不同 owner 各自獨立，不互相去重。
時間：排序與 ?since 一律用伺服器收到的 received_at（毫秒）；手機送來的時間原樣存在 device_time。
驗證碼抽取：寫入時自動抓 code，支援銀行、蝦皮、Google 的 G-847291、英文 "Use 483920 to log in"、OTP: 0042 等格式。訂單編號、手機號、年份會正確地不抓。

🔒 驗證（選配，目前關閉）

伺服器沒設 API_TOKEN 時所有端點都不需要驗證。
想鎖起來的話，設了 API_TOKEN 之後寫入與刪除自動要 token；讀取預設放行，再設 REQUIRE_READ_AUTH=1 也要 token。

# 帶 token 的方式（二擇一）
Authorization: Bearer <API_TOKEN>
X-Api-Key: <API_TOKEN>