mail-otp — API

Disposable mailbox for verification codes. One request per attempt: it answers in milliseconds when the code is already there, and otherwise the instant it lands.

Retention   10 minutes, newest mail per address only
Long poll   a read is held for up to 60s while the mailbox is empty

GET /api/mailboxes/:address
  Return the mailbox's current code, or hold the connection for up to 60s until one arrives. :address is a full address, such as alice@vectflux.com.
  Query:
    since=-    Only accept a mail newer than this (epoch milliseconds or ISO-8601). Pass a timestamp taken before you triggered the send and a stale code can never come back.
    consume=0  1 empties the mailbox after a successful read.
    body=1     0 omits mail.text and mail.html.
  200 → {"found":true,"address":"alice@vectflux.com","code":"462718","confidence":"high","id":"…","receivedAt":1785957468732,"receivedAtIso":"…","expiresAt":…,"expiresInMs":…,"mail":{"subject":"…","from":{…},"to":[…],"date":"…","messageId":"…","size":424,"text":"…","html":"…"}}
  200 → {"found":false,"address":"alice@vectflux.com","waitedMs":60000} — the wait elapsed
  400 → {"error":"Invalid mailbox address"} — also for a malformed since

GET /api/mailboxes/:address/code
  The same waiting behaviour with a plain-text body: just the code, or an empty 404.
  Query:
    since=-    Only accept a mail newer than this (epoch milliseconds or ISO-8601). Pass a timestamp taken before you triggered the send and a stale code can never come back.
    consume=0  1 empties the mailbox after a successful read.
    body=1     0 omits mail.text and mail.html.
  200 → 462718
  404 → (empty) — nothing arrived within the wait window

DELETE /api/mailboxes/:address
  Empty one mailbox. Call it before triggering a send to guarantee a fresh code.
  200 → {"address":"alice@vectflux.com","deleted":true}

Shell
  curl "http://otp.vectflux.com/api/mailboxes/alice@vectflux.com"
  CODE=$(curl -sf "http://otp.vectflux.com/api/mailboxes/alice@vectflux.com/code?consume=1")

Recommended client flow
  const box = 'signup-' + Date.now() + '@vectflux.com';
  const since = Date.now();
  await triggerSignup(box);
  const res = await fetch(`${API}/api/mailboxes/${box}?since=${since}`);
  const { found, code } = await res.json();