WispInbox

WispInbox API

Create disposable inboxes and wait for OTP codes in automated QA flows. Built for Playwright, Cypress, and any HTTP client.

Base URL https://wispinbox.com Auth Bearer token Format JSON

OTP API access

Free mailboxes get 3 OTP API calls/day. Pro mailboxes are unlimited.

Upgrade to Pro

Authentication

There is no separate “API keys” page. Your Bearer token is created automatically when you open a disposable inbox via the API.

How to get a Bearer token

  1. Call POST /api/mailbox (no auth required for a new inbox).
  2. Copy the token field from the JSON response.
  3. Send Authorization: Bearer <token> on routes marked with the lock badge.

Example response: {"address":"…@wispinbox.com","token":"abc123…","expiresAt":…} — treat token like a password for that inbox only.

Authorization header required

Bearer <token> on protected endpoints (/api/messages, /api/otp, etc.).

In the browser app, the same token is stored in an HttpOnly cookie. For cookie-based calls from JS, send X-Requested-With: fetch. Google/GitHub login is only for Pro account features — not required for basic API use.

Getting started

Typical OTP automation flow for signup tests:

  1. Create a mailbox with POST /api/mailbox (optionally set a predictable name).
  2. Fill that address in your app’s signup / login form.
  3. Long-poll GET /api/otp until the verification code arrives.

Rate limits

GET /api/otp (free) quota

3 calls per mailbox per day by default (OTP_API_FREE_LIMIT_PER_DAY).

GET /api/otp (Pro) quota

Unlimited OTP wait calls for Pro addresses.

429 otp_api_limit error

Returned when the free daily quota is exhausted. Upgrade that address to Pro to continue.

GET /api/config

Public site configuration: domains, TTL, and feature flags.

POST /api/mailbox

Create a new disposable mailbox. Returns address, token, and expiresAt.

name string optional

Local-part of the address (e.g. signup-e2e-123). Random if omitted.

domain string optional

Must be one of the configured domains (e.g. wispinbox.com).

GET /api/mailbox bearer

Return the current mailbox for this token/session.

DELETE /api/mailbox bearer

Delete a free mailbox (or clear the session for owned Pro addresses).

GET /api/messages bearer

List inbox summaries, newest first.

GET /api/otp bearer

Long-poll until an OTP-like code arrives. Ideal for QA: no UI scraping required. Default wait is 45s (max 120s).

timeoutMs integer optional

Wait time in ms. Default 45000, max 120000.

digits integer optional

OTP length when pattern is not set. Default 6 (3–10).

pattern string optional

Custom regex. First capture group is returned as code.

flags string optional

Regex flags for pattern (i, m, s, u).

after string optional

Only match mail received after this unix-ms timestamp or ISO date (server arrival time). Use this on every signup / resend so you don’t pick up an older code already in the mailbox. Caveat: a late first email can still arrive after your resend stamp — pair with markSeen=1 + unseenOnly=1, assert the code changed, or use a fresh mailbox per attempt.

subjectIncludes string optional

Case-insensitive subject filter.

fromIncludes string optional

Case-insensitive sender filter.

unseenOnly boolean optional

1/true to match unread mail only.

markSeen boolean optional

1/true to mark the matched message as seen.

GET /api/messages/:id bearer

Full message including html, text, and attachments metadata.

GET /api/events?token=…

Server-Sent Events stream for live inbox updates (mail, expired).