一次性郵箱 API：開發者實戰指南

網頁版收件匣對人類很好用，但測試與自動化需要的是一次性郵箱 API：一種能用程式建立拋棄式地址、讀取裡頭收到的任何東西、再把它收掉的方式。這篇指南會帶你看清各個組件，以及如何用 MoeMail 的臨時郵箱 OpenAPI 把它們串起來。

為什麼要用 API，而不是網頁收件匣？

註冊、郵件驗證與密碼重設流程，是端對端測試裡最難搞的幾件事，因為驗證步驟會離開你的應用程式、落到某個收件匣裡。一次性郵箱 API 把這個迴圈補上：你的測試先開一個全新收件匣、觸發流程，再向 API 輪詢驗證訊息並抽出連結或驗證碼——結果可預期，也沒有共用的人類信箱被污染。

用 API key 認證

MoeMail 用放在 X-API-Key 標頭裡的 API key 來認證程式發出的請求。登入後從個人檔案產生一把 key，再把它附在每個請求上。Key 的權限範圍限定在郵件與設定端點，並受你帳號的每月配額限制，所以請把它當機密看待，外洩就立刻輪替。

核心操作

• 建立郵箱——以指定的過期時間，申請一個新的隨機或自訂地址。
• 列出訊息——輪詢郵箱，看有沒有剛收到的新郵件。
• 讀取訊息——取得單封訊息的標頭、純文字與 HTML 內文。
• 讓它過期——什麼都不用做；郵箱與其訊息會自動被清理掉。

一個最精簡的輪詢呼叫，大概就是把你的 key 當成標頭送到郵件端點，例如：curl -H "X-API-Key: YOUR_KEY" https://moemail.app/api/emails。確切的請求與回應格式都記錄在 OpenAPI 定義裡。

Webhook：別再輪詢了

輪詢能用，但它會增加延遲、浪費請求。MoeMail 可以在訊息抵達的當下觸發一個 webhook，讓你的測試或後端立刻反應，而不是一直繞圈圈。把 webhook 指向一個你的測試框架掌控的端點，驗證 payload，等訊息一落地就把等待中的步驟結束掉。處理函式要快——在幾秒內回應，因為太慢或非 2xx 的回應都會觸發重試。

速率限制與配額

API 用量會計入你帳號的每月 OpenAPI 配額。面對大型測試套件，能共用郵箱做多次斷言就盡量共用、把輪詢批次化，並優先用 webhook 取代密集的輪詢迴圈。如果需要更多餘裕，較高的角色等級與商店配額可以調高上限——或者乾脆自己跑一份（見自託管 vs 託管臨時郵箱）。

在測試裡組起來

不管你用 Playwright、Cypress 還是 Selenium，模式都一樣：把建立／輪詢／讀取這幾個呼叫包進一個小幫手（fixture 或自訂指令），在測試開頭開一個收件匣，把 UI 推進到驗證步驟，再透過這個幫手等待訊息。因為每次執行都拿到自己的地址，測試之間互不干擾，平行跑也安全。

下一步

讀完整 API 文件、從個人檔案抓一把 key，先試一趟「建立加輪詢」的來回。接著把它端對端自動化：看如何自動化郵件驗證測試與用 webhook 接收郵件。對這個概念還陌生？先從什麼是臨時郵箱開始，或乾脆到後台建立一個郵箱，看看 API 回傳什麼。