Skip to content
Postern Postern Docs

API · wait_for_email

The blocking receive primitive. The request stays open (long-poll, IMAP IDLE server-side) until a matching message arrives or the timeout elapses, then returns it with the OTP code and verification link already extracted.

POST /v1/inboxes/{addr}/wait

Section titled “POST /v1/inboxes/{addr}/wait”

Request

Section titled “Request”
{
  "from": "no-reply@acme.test",   // optional — match sender (substring, case-insensitive)
  "subject": "verification",      // optional — match subject (substring, case-insensitive)
  "regex": "\\b\\d{6}\\b",        // optional — match the body
  "since": "2026-06-12T18:00:00Z",// optional — only newer messages (default: now)
  "timeout_seconds": 120          // optional — server-capped (default 120, max 300)
}
Terminal window
curl -sS -X POST \
  "$POSTERN_API_BASE_URL/v1/inboxes/signup-agent%40x4p.mszazu.com/wait" \
  -H "Authorization: Bearer $POSTERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "no-reply@acme.test", "subject": "verification", "timeout_seconds": 120 }'

Response 200 — matched

Section titled “Response 200 — matched”
{
  "timed_out": false,
  "message": {
    "id": "msg_8Tz",
    "thread_id": "thread_9aB",
    "from": "no-reply@acme.test",
    "subject": "Verify your email",
    "received_at": "2026-06-12T18:05:42Z"
  },
  "extracted": {
    "otp_code": "492013",
    "verification_link": "https://acme.test/verify?token=…",
    "credentials": null
  }
}

Response 200 — timed out

Section titled “Response 200 — timed out”
{ "timed_out": true, "message": null, "extracted": null }

A timeout is a normal 200, not an error — the agent decides whether to retry, lengthen the wait, or re-trigger the upstream sign-up.

Extraction

Section titled “Extraction”
FieldMeaning
otp_codeThe one-time code, if found.
verification_linkThe first click-through verification URL, if found.
credentialsUsername/password pairs, when present.

Next

Section titled “Next”