Build email into
your workflow.

Use a Developer account API key with messages:read. The inbox must belong to that key’s account. Public inboxes, RevenueCat mobile inboxes, and website session cookies do not authorize this endpoint.

The response uses text/event-stream. Older deliveries are excluded even if parsed after connection; new mail must finish parsing before the stream closes. Heartbeat comments keep the connection active while waiting.

Start a new request for another window. Query parameters and Last-Event-ID replay are not supported. The cURL client timeout of 70 seconds allows time for the server’s 60-second window.

A stream.error event means access or service failure interrupted the stream; start a new request after resolving the cause.

code is a string, preserving leading zeroes. Each candidate includes inbox_id, message_id, sender, subject, received_at, and expires_at. The timestamps describe the message’s server receipt and retention deadline; they do not establish when the OTP itself expires. Sender and subject metadata are limited to 1,024 characters each.

confidence is high for an explicit nearby OTP label or medium for a generic code/PIN label or an OTP subject with a code near the start of the body. confidence_score is an uncalibrated rule score, not a probability or percentage accuracy. signals explains the match, and source identifies subject, text, or html. The service does not verify the sender or validate the code with its issuer; reliability.verified is always false.

Extraction supports labelled 4–8 digit codes, including grouped six-digit codes, and mixed uppercase-letter/digit codes of 6–10 characters. It scans the subject and the first 128 KiB of plain text, with a fallback for HTML-only messages. Attachments are not scanned. Codes repeated within one message are deduplicated, with at most 16 candidates per message. False positives and missed codes are possible.

Each connection consumes one API request; streamed candidates do not consume extra requests. Concurrency is limited across the account’s keys. Cancellation, revoked access, inbox deletion, service failure, or a slow consumer can end the stream early. A complete event with reason: timeout is normal, including when codes_found is zero.

Before streaming starts, HTTP 401 indicates a missing, invalid, or revoked key; HTTP 403 indicates a missing scope or unavailable plan feature; HTTP 404 means the inbox is unavailable or not owned by the account. HTTP 422 rejects invalid parameters or a replay cursor, and HTTP 429 indicates a request or stream limit.

Each event has an event: line and a single-line JSON data: value, separated from the next event by a blank line. The panel above formats the decoded JSON for readability.

event: ready
data: {"inbox_id":"INBOX_ID","started_at":"2026-10-14T12:00:00.000Z","deadline":"2026-10-14T12:01:00.000Z","extraction_version":"otp-heuristic-v1"}

event: otp.found
data: {"inbox_id":"INBOX_ID","message_id":"MESSAGE_ID","sender":"[email protected]","subject":"Your verification code","received_at":"2026-10-14T12:00:01.000Z","expires_at":"2026-11-13T12:00:01.000Z","code":"001234","source":"text","confidence":"high","confidence_score":95,"signals":["explicit_otp_label","numeric_code"],"reliability":{"method":"heuristic","verified":false}}

event: complete
data: {"reason":"timeout","codes_found":1,"finished_at":"2026-10-14T12:01:00.000Z"}