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 is unlimited from ₹35/month. Custom domain means BYOD (bring your own domain/subdomain).

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. Save address and token.
  2. Write down the time. That value is after. Do this before you submit the form.
  3. Paste address into the signup form and submit.
  4. Call GET /api/otp?after=<that time>. The call waits until a code arrives, then returns code.

after means “only mail that arrived after this moment.”

Without it, /api/otp can return an older code already sitting in the inbox. With it, those older messages are skipped.

Two formats work:

  • Unix milliseconds: after=1760050800000
  • ISO time: after=2026-10-10T00:20:00.000Z

Shell: AFTER=$(date +%s000) then ?after=$AFTER. JavaScript: const after = new Date().toISOString() before the form submit.

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

Waits until an OTP-like code arrives, then returns it as JSON. Default wait is 45s (max 120s).

Pass after on every wait. Save the current time, submit the form, then call this endpoint with that time.

GET /api/otp?timeoutMs=90000&digits=6&after=2026-10-10T00:20:00.000Z&markSeen=1

Resend: save a new time, click Resend, and call again with unseenOnly=1 so a delayed first email is not treated as the new code.

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

Skip any mail that arrived at or before this time. Use unix milliseconds (1760050800000) or an ISO date (2026-10-10T00:20:00.000Z). Save it before you submit the form or click Resend. On a resend, also send unseenOnly=1, because a slow first email can still arrive after the new timestamp.

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).