EZMAIL API 操作手冊及入門指南

歡迎使用 EZMAIL API，本手冊提供操作指引、常見問答及版本更新資訊等，協助您將 EDM 發送功能無縫且順利的整合至公司平台系統。

適用對象

本 API 適用於企業內部的技術開發人員，協助整合 EDM 發送功能至公司現有平台或系統。

驗證方式

本 API 使用 API Key 進行驗證。 請在每一次受保護的請求中，於 HTTP Header 中加入 API Key。

Authorization: Bearer <YOUR_API_KEY>

API Key 申請機制與使用注意事項

• 請聯絡技術支援申請專屬 API Key。
• 每位客戶配發一組專屬 API Key，請依實際需求申請。
• 請妥善保存您的 API Key，勿公開於網頁、GitHub 或第三方平台。
• 若 API Key 遺失或疑似外洩，請立即通知技術支援進行停用及重發。
• API Key 僅能用於授權用途，請勿用於其他未經授權的行為。

IP 白名單機制說明

API 伺服器僅允許在白名單內的 IP 位址進行存取。

• 請提供您的伺服器或用戶端的固定 IP，並聯絡技術支援申請加入白名單。
• 若您的 IP 未在白名單內，API 會回應 403 Forbidden。
• 若有 IP 變更或需新增/移除，請隨時通知技術支援。
• 可設定多組 IP，並不支援 CIDR 格式（如 192.168.1.0/24）。

流量限制

• 每組 API Key 每分鐘最多可呼叫 60 次。
• 超過流量限制時，API 會回應 429 Too Many Attempts。
• 請依建議頻率設計您的程式，避免因流量過高導致服務暫時受限。

回應格式說明

本 API 採用統一的 JSON 格式回應，回應內容包含以下欄位，並搭配對應的 HTTP 狀態碼：

• success (boolean)：請求是否成功，true 表示成功，false 表示失敗。
• message (string)：請求結果的描述訊息，例如「操作成功」或「清單不存在」。
• data (object ｜ array ｜ null)：回應的實際資料內容；若無資料則為 null。
• HTTP 狀態碼 (integer)：回應的 HTTP 狀態碼，例如：
  • 200 OK：請求成功
  • 201 Created：資源建立成功
  • 204 No Content：成功，但無回傳資料
  • 400 Bad Request：請求格式錯誤或驗證失敗
  • 401 Unauthorized：驗證失敗，缺少或錯誤的 API Key
  • 404 Not Found：資源不存在
  • 500 Internal Server Error：伺服器錯誤

成功範例 (HTTP 201)

{
  "success": true,
  "message": "群組建立成功",
  "data": {
    "id": 1000,
    "name": "行銷名單",
    "description": "VIP 客戶群",
    "created_at": "2025-09-11 12:00:00"
  }
}

API Endpoint 清單

完整的 API 路徑資源及 HTTP 方法，請參閱 API Reference 端點參考文件。

如何上傳名單

使用端點 /api/v1/members/import 匯入會員

檔案格式

• 上傳檔案格式：CSV
• 建議編碼：UTF-8
• 檔案大小：20MB
• 第一行需為標題列，欄位如下：
  • email (必填) – 訂閱者的電子郵件
  • name (選填) – 訂閱者姓名
  • company (選填) – 公司名稱
• 第二行開始為資料內容。

範例檔案 (subscribers.csv)

email,name,company
john.doe@example.com,John Doe,Example Inc.
jane.smith@example.com,Jane Smith,ACME Corp

發送 EDM 的簡易流程

• 將會員 (Member) 整理成 CSV 檔後匯入清單
• 建立群組 (Group)，包含上述清單
• 新增電子報 (Edm)，發送對象為上述目標群組
• 將電子報送入排程 sceduled
• 等待預約時間到系統會自動開始發送 sending
• 可查詢開信、點擊、退信及取消訂閱的發送報告

常見問答 (FAQ)

Q: API Key 遺失怎麼辦？

A: 請立即聯絡技術支援，協助停用原有 API Key 並重新申請。

Q: 為什麼收到 403 Forbidden？

A: 請確認您的 IP 是否已加入白名單，若未加入請聯絡技術支援。

Q: API 回應 429 Too Many Requests 是什麼原因？

A: 表示流量超過限制，請降低呼叫頻率或稍後再試。

Q: API Key 可以公開在前端網頁嗎？

A: 請勿將 API Key 公開於前端網頁，應僅用於伺服器端，避免資訊外洩與安全風險。

Q: 如何新增或移除白名單 IP？

A: 請聯絡技術支援，提供需新增或移除的 IP 位址。

Q: 如何變更寄件人信箱？

A: 請聯絡技術支援，提供需變更的寄件人信箱，完成後續的 SPF 及 DKIM 設定。

Q: 如何聯絡技術支援？

A: 如有任何問題或建議，您可透過以下方式聯絡技術支援：

• Email：service@ezmail.com.tw
• 客服電話：(03)3688-258

版本變更說明

• 2025-09-19：v1.0.1 版本上線。
• 2025-09-11：v1.0.0 版本上線。