member_center/docs/MESSMAIL.md

租戶站台介接指引（Member Center + Send Engine）

此文件給租戶站台使用，描述如何：

• 訂閱 / 確認 / 退訂 / 偏好管理（Member Center）
• 建立發信任務（Send Engine）

不包含 Member Center ↔ Send Engine 的內部事件同步細節。

---

1. 系統流程圖（租戶站台角度）

Tenant Site
  |
  | (1) Subscribe
  v
Member Center
  |
  | (2) Send confirmation email
  v
End User
  |
  | (3) Confirm link
  v
Member Center

Tenant Site
  |
  | (4) Request unsubscribe token
  v
Member Center
  |
  | (5) Unsubscribe with token
  v
Member Center

Tenant Site
  |
  | (6) Create send job
  v
Send Engine
  |
  | (7) Deliver via ESP
  v
End User

---

2. Auth / Scope（租戶站台）

租戶站台沒有真人帳號，使用 Client Credentials 取得 access token。

• 向 Member Center 申請 OAuth Client
• OAuth Client 建議使用 usage=send_api（專供發送）；tenant_api 留給其他租戶 API
• scope 依用途最小化

建議 scopes：

• newsletter:send.write（Send Engine 建立發信任務）
• newsletter:send.read（查詢發信狀態，若需要）

Send Engine 會驗證 token 內的 tenant_id 與 scope。

取得 Token（範例）

curl -s -X POST https://{member-center}/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&scope=newsletter:send.write"

使用 Token（範例）

curl -s -X POST https://{send-engine}/api/send-jobs \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ \"tenant_id\": \"<TENANT_ID>\", \"list_id\": \"<LIST_ID>\", \"subject\": \"Weekly\", \"body_text\": \"Hello\" }'

Send Engine 驗證 Token（JWT / JWKS）

• Send Engine 以 Member Center 的 JWKS 驗簽 access token（JWS）。
• 驗證重點：iss、aud、scope、tenant_id、exp。
• iss：由 Member Center Auth__Issuer 設定（例：http://localhost:7850/）
• aud：Send Engine 流程預設 send_engine_api（可用 Auth__SendEngineAudience 覆寫）

---

3. API 表格（租戶站台 → Member Center）

功能	Method	Path	必填	說明
訂閱	POST	/newsletter/subscribe	list_id, email	回傳 confirm_token
確認訂閱	GET	/newsletter/confirm	token	double opt-in 確認
申請退訂 token	POST	/newsletter/unsubscribe-token	list_id, email	回傳 unsubscribe_token
退訂	POST	/newsletter/unsubscribe	token	單一清單退訂
讀取偏好	GET	/newsletter/preferences	list_id, email	需 list_id + email
更新偏好	POST	/newsletter/preferences	list_id, email, preferences	需 list_id + email

---

訂閱（範例）

curl -s -X POST https://{member-center}/newsletter/subscribe \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": "<LIST_ID>",
    "email": "user@example.com",
    "preferences": {"lang": "zh-TW"}
  }'

申請退訂 token（範例）

curl -s -X POST https://{member-center}/newsletter/unsubscribe-token \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": "<LIST_ID>",
    "email": "user@example.com"
  }'

退訂（範例）

curl -s -X POST https://{member-center}/newsletter/unsubscribe \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<UNSUBSCRIBE_TOKEN>"
  }'

---

4. API 表格（租戶站台 → Send Engine）

功能	Method	Path	必填	說明
建立發信任務	POST	/api/send-jobs	list_id, subject, body_html/body_text	發送排程
查詢發信任務	GET	/api/send-jobs/{id}	id	讀取狀態
取消發信任務	POST	/api/send-jobs/{id}/cancel	id	取消發送

建立發信任務（範例）

curl -s -X POST https://{send-engine}/api/send-jobs \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "<TENANT_ID>",
    "list_id": "<LIST_ID>",
    "name": "Weekly Update",
    "subject": "Weekly Update",
    "body_html": "<p>Hello</p>",
    "body_text": "Hello",
    "scheduled_at": "2026-02-11T02:00:00Z"
  }'

---

5. 安全注意事項（租戶站台）

• list_id + email 為租戶隔離最小邊界，必須一併提供
• 不要保存退訂 token；使用時再向 Member Center 申請
• Token 必須妥善保管，避免跨租戶濫用