OTPBox developer API documentation

Create disposable inboxes and read one-time codes from a test suite, script, or backend job. Start with a free key — no account needed — or create an organization to share keys with a team and upgrade.

Try it now

Live against the real API, right from this page — no signup. Mints a real (rate-limited) free key, creates a real inbox, then checks it for a message. Send the inbox address a real email from another tab to see it show up.

Click "Mint a free key" to start.

Get a key

Free, 200 requests/month, simple bearer-token auth. Mint one instantly, no payment or account:

curl -X POST https://otpbox.io/api/v1/keys/free \
  -H "content-type: application/json" \
  -d '{}'
→ { "id": "lic_...", "key": "...", "plan": "free", "quotaLimit": 200 }

Save the returned key — like an inbox token, it's shown once and never stored anywhere you can read it back from. Limited to 5 free keys/day per IP.

Sandbox keys for CI. POST /api/v1/keys/sandbox mints a key the same way (no account, same 200 requests/month, its own 5/day/IP limit) and returns { "id": "lic_...", "key": "...", "plan": "free", "quotaLimit": 200, "sandbox": true }. With a sandbox key, POST /api/v1/inboxes (and the MCP create_test_inbox tool) skips real mail: the new inbox already contains one synthesized message from noreply@sandbox.otpbox.io with a random 6-digit code, so a test run is fully deterministic and needs no real delivery. Sandbox inboxes never receive real mail, so they never fire message.received, otp.extracted or link.detected webhooks.

Free keys and consumer platforms. Free keys (personal and organization) are for testing your own app's email. Mail from consumer platforms such as Reddit, Meta (Facebook, Instagram, WhatsApp), TikTok, X, Snapchat, Discord, LinkedIn and Twitch is refused at delivery, so the sender gets a bounce and nothing is stored. Paid plans are not restricted this way, and neither are inboxes created on the website without a key.

Plans

Quotas are per monthly billing cycle that starts on your signup day: an organization's cycle starts the day the organization was created, and a personal free key's the day it was minted. Organization plans pool the quota across every key the organization mints; a personal free key has its own. Full details on the pricing page.

Check what a key is entitled to at any time with GET /api/v1/usage — it returns the plan, the governing limit, and how much of it has been used this cycle, and the date it resets.

Authentication

Send your key as a bearer token on every request:

Authorization: Bearer <your-key>

Endpoints

All paths are under https://otpbox.io. Every route except the two key-minting routes needs Authorization: Bearer <key>, and every authenticated request counts as one request against your monthly quota. Timestamps are Unix milliseconds. Bodies and responses are JSON.

Inboxes are deleted when they expire — 1 hour after creation by default — or as soon as you delete them. The message list only reports what was extracted (code, linkHost, linkType); fetch the full message for the link URL. linkType (and link.type) is one of verification, password_reset, magic_login, unsubscribe, tracking or general.

Example message response:

{
  "id": "msg_a1b2c3d4e5f6",
  "from": "noreply@example.com",
  "fromName": "Example",
  "subject": "Your verification code",
  "text": "Your code is 482913",
  "html": null,
  "code": "482913",
  "link": { "url": "https://example.com/verify?t=...", "host": "example.com", "type": "verification" },
  "size": 2048,
  "receivedAt": 1790000000000,
  "attachments": [],
  "preview": "Your code is 482913"
}

Example: get a code in a Playwright test

const key = process.env.OTPBOX_KEY;
const res = await fetch('https://otpbox.io/api/v1/inboxes', {
  method: 'POST',
  headers: { authorization: 'Bearer ' + key, 'content-type': 'application/json' },
  body: '{}',
});
const inbox = await res.json();
// use inbox.address to sign up, then poll:
const msgs = await fetch('https://otpbox.io/api/v1/inboxes/' + inbox.id + '/messages', {
  headers: { authorization: 'Bearer ' + key },
}).then((r) => r.json());
const code = msgs.messages[0]?.code;

Waiting for mail

Don't poll. Ask for the next code or message and the request is held open until it arrives (or the timeout passes), so a test costs one request instead of dozens.

POST /api/v1/inboxes/:id/wait
{ "timeoutSeconds": 20, "requireOtp": true, "subject": "verification" }

→ 200 { "timedOut": false, "message": { "id": "...", "from": "...", "subject": "...", "code": "482913", "link": null, "text": "...", "html": "...", "attachments": [] } }
→ 200 { "timedOut": true, "message": null }          // nothing matching arrived in time

• timeoutSeconds is 1–25 (default 20). A timeout is a normal 200 with timedOut: true, not an error — just call again.
• By default only mail that arrives after the call counts. Pass since (epoch milliseconds — use the inbox's createdAt) to also match mail that is already there, which avoids a race if the email lands before you start waiting.
• Narrow what counts as a match with from (substring of the sender address or name), subject (substring), messageId, requireOtp and requireLink. Substring filters are literal and case-insensitive.
• GET /api/v1/inboxes/:id/otp and /links take the same filters as query parameters (from, subject, messageId, since) and an optional timeout in seconds (0–25, default 0). With timeout they wait for the first match; without it they return the newest immediately. Nothing found is 404 no_otp (with timedOut: true if it waited) or an empty links list.
• Each call is one metered request however long it waits. Waiting is capped at 25 seconds per call.

// Playwright: type the address, then get the code
await page.fill('[name=email]', inbox.address);
await page.click('text=Send code');
const { code } = await (await fetch(`https://otpbox.io/api/v1/inboxes/${inbox.id}/otp?timeout=20`, { headers })).json();
await page.fill('[name=code]', code);

Batches

Create up to 50 inboxes in a single call — handy for provisioning a whole test matrix up front. The batch runs synchronously and returns every address and token in the response.

POST /api/v1/batches
{ "count": 3, "ttlHours": 2 }

→ 201
{
  "id": "batch_...",
  "status": "partial",
  "requestedCount": 3,
  "items": [
    { "id": "a1b2c3d4e5f6", "status": "completed", "address": "bold.quartz844@otpbox.io", "token": "...", "expiresAt": 1790007200000 },
    { "id": "bi_...", "status": "failed", "error": "address_unavailable" }
  ]
}

• count is required, 1–50; anything else returns 400 { "error": "bad_count", "max": 50 }. ttlHours is optional and capped at the server maximum (currently 3 hours); without it, the default inbox lifetime applies.
• Batch status is completed (every item succeeded — the batch is ready to use), partial (some failed), failed (none succeeded), cancelled (you cancelled it) or expired (it provisioned inboxes but none are still alive). Whether the tests that use a batch passed is your framework's call, so there is no running state. A completed item's id is the inbox id, so you can read it with GET /api/v1/inboxes/:id/messages. (The example above is abbreviated to two items.)
• Each item's token is the inbox's own bearer token. It is only returned by this create call.
• GET /api/v1/batches/:id returns { id, status, requestedCount, activeCount, createdAt, completedAt, cancelledAt, items: [{ id, status, address, expiresAt, error }] } (no tokens); id is null for a failed item. Unknown or someone else's batch: 404 not_found.
• POST /api/v1/batches/:id/cancel destroys every inbox the batch still holds and marks it cancelled (scope inbox:delete); repeating it is a harmless no-op, and a batch that is still being created returns 409 batch_still_creating.
• Requires the bulk:create scope and accepts an Idempotency-Key. 503 no_domains if no mailbox domain is currently available.

Bulk provisioning (Enterprise)

When a test programme needs thousands of addresses that live for weeks — a seeded QA environment, a load test, a long-running signup regression — ask for a pool in one call instead of creating inboxes one by one. A job is accepted straight away and the inboxes are created in the background (10,000 take about a minute); you follow it, then download the address list. Bulk provisioning is part of Enterprise plans: your agreement sets the largest pool you can hold and the longest lifetime a pool may have.

POST /api/v1/provisioning-jobs
Authorization: Bearer <key>
{ "count": 10000, "lifetime": "90d", "pattern": "qa-{n}", "domain": "qa.example.com" }

202 Accepted
{
  "id": "prov_...", "status": "queued", "requestedCount": 10000, "createdCount": 0, "progress": 0,
  "domain": "qa.example.com", "pattern": "qa-{n:5}", "startAt": 1, "lifetimeHours": 2160, "expiresAt": 1798000000000,
  "exportUrl": "https://otpbox.io/api/v1/provisioning-jobs/prov_.../export?format=csv"
}

• count is required: 1 up to your pool size (and at most 50,000 per job). lifetime is "12h", "90d" or "never" (until you release the pool), or send lifetimeHours as a number; without either, pools live 30 days (or your maximum, if that is shorter). prefix (optional, up to 16 of a-z0-9._-) starts every address, followed by 8 random characters. domain is optional: one of your organization's verified custom domains, or leave it out and OTPBox picks one.
• Follow the job with GET /api/v1/provisioning-jobs/:id (or list them with GET /api/v1/provisioning-jobs). status goes queued → running → completed (or partial / failed if addresses could not be allocated, with error saying why). Subscribe a webhook to provisioning.completed to be told instead of polling.
• GET /api/v1/provisioning-jobs/:id/export streams address,inbox_id,created_at,expires_at as CSV; ?format=json returns { jobId, inboxes: [{ id, address, createdAt, expiresAt }] }. Only live inboxes are listed. Members can also download it from the dashboard's Provisioning page.
• Pool inboxes belong to the project: every key in the project can read them with the usual routes (GET /api/v1/inboxes/:id/otp, POST /api/v1/inboxes/:id/wait and so on), so rotating or revoking the key that created the pool doesn't lock you out. Webhooks for their mail fire on the key that created the job.
• POST /api/v1/provisioning-jobs/:id/cancel stops a job that is still running (the inboxes made so far stay). POST /api/v1/provisioning-jobs/:id/release with { "confirm": true } ends every inbox in a finished pool at once (scope inbox:delete); they stop accepting mail immediately and are removed by the cleanup job.
• One job runs at a time per organization (409 job_in_progress), and live pools across all jobs can't exceed your pool size (409 pool_limit with limit and live). Creating the job is one request against your quota; reads count as usual. Accepts an Idempotency-Key.
• Naming. pattern holds exactly one token among literal a-z0-9._-: {n} numbers the addresses (qa-{n} with 10,000 inboxes gives qa-00001 … qa-10000; {n:W} fixes the width, startAt sets the first number, default 1) and {random} adds 8 random characters. The longest address it can produce must fit in 32 characters. With {n}, a number already in use (say, by an earlier pool) is skipped and counted in failedCount; the job ends partial with error: "address_taken". prefix is shorthand for "<prefix>{random}".
• Inbox-days. GET /api/v1/provisioning/usage returns your pool size, your agreement's limits and usage: { period, resetsOn, inboxDays, allowance, overage, peak, daily: [{ day, inboxDays, peak }] } for the current billing cycle. An inbox-day is one pool inbox kept for one day, measured every 15 minutes: 10,000 inboxes held all day are 10,000 inbox-days. The dashboard's Provisioning page shows the same numbers, and when each billing cycle closes the cycle's requests and inbox-days are kept as a statement on the Billing page (downloadable as CSV) — the usage record your Enterprise invoice is based on.
• Message retention. Your agreement can cap how long pool messages are kept (older ones are deleted, checked every 15 minutes) and how many each pool inbox keeps (only the newest are kept as mail arrives). Both appear under settings in the usage response.
• Expiry. When a pool's lifetime runs out, its inboxes stop accepting mail and are cleared in bulk; the job becomes expired and provisioning.expired fires once. Pool inboxes never send the per-inbox inbox.expiring or inbox.expired webhooks.

Test identities

A test identity is a synthetic persona — name, country and a small profile — backed by a real disposable inbox, so a signup flow under test can use a realistic person and still receive its verification email. Pick a template: us_customer, indian_customer, european_customer, business_customer, student or employee.

POST /api/v1/identities
{ "template": "business_customer", "ttlHours": 2 }

→ 201
{
  "id": "ident_...",
  "status": "active",
  "template": "business_customer",
  "name": "Mary Johnson",
  "email": "bold.quartz844@otpbox.io",
  "country": "US",
  "profile": { "company": "Acme Corp", "role": "Product Manager" },
  "token": "...",
  "createdAt": 1790000000000,
  "expiresAt": 1790007200000
}

• Use email in the form under test. token is the backing inbox's bearer token, shown only in this response; use it with the public inbox API (GET /api/inboxes/me/messages with Authorization: Bearer <token>) to read what arrives.
• The persona's profile depends on the template: business_customer adds company and role, student adds university and major, employee adds company, department and jobTitle; the customer templates return an empty profile.
• ttlHours is optional and capped at the server maximum (currently 3 hours). Errors: 400 bad_template (with validTemplates), 409 address_unavailable, 503 no_domains.
• POST /api/v1/identities/bulk with { "template", "count", "ttlHours"? } (count 1–50, else 400 bad_count) returns 201 { batchId, template, requestedCount, items: [...] }; batchId looks like idbatch_.... Each item is { id, status: "active", name, email, country, profile, token, expiresAt }, or { id, status: "failed", error }.
• GET /api/v1/identities/:id returns the identity without its token, plus batchId and error. DELETE /api/v1/identities/:id deletes the identity and its backing inbox and returns { ok: true, id, inboxDeleted }. Unknown ids return 404 not_found.

Agents and request IDs

In the dashboard, an organization can register agents — named clients such as “Signup Regression Agent” — with an environment (production, staging, development, ci) and give each its own keys. Everything a key does over REST or MCP is attributed to its agent: the dashboard shows requests today, live inboxes, MCP call latency and errors, and a log of recent calls.

• Daily cap — an optional limit on requests per UTC day across all the agent's keys. Over it, calls return 429 agent_daily_limit (and aren't counted against your plan).
• Concurrent inbox cap — an optional limit on live inboxes at once. Creating more (an inbox, batch or identity) returns 429 agent_concurrency_limit until some expire or are deleted.
• Pause — a paused agent's keys get 403 agent_paused until you resume it. Useful as a kill switch for a runaway loop.

Every API response carries an x-request-id header. Send your own (8–64 characters of A-Za-z0-9._-) to correlate a call with your test run; it is recorded on the MCP call log and on the organization's audit log, so quote it to support and we can find the exact call.

Runs and timelines

A run is one test execution. Give it any id you like and OTPBox ties every event that test causes into one ordered timeline — identity created, signup submitted, email received, OTP extracted, OTP supplied, test completed — so a slow or failed run can be diagnosed from a single page instead of from scattered logs.

• Header: send X-OTPBox-Run: <runId> on REST and MCP HTTP requests. The id is 8–64 characters of A-Za-z0-9._:-; anything else returns 400 bad_run_id and nothing is created.
• Body field: runId in the JSON body of POST /api/v1/inboxes, /batches, /identities and /identities/bulk, or as an optional argument on the MCP tools create_test_inbox, create_test_identity, create_bulk_test_identities and create_batch. A body field wins over the header.
• It sticks to what it creates. An inbox or identity created under a run remembers it, so mail that arrives later (which has no header) and calls that omit the header still land on the same run. Send the header explicitly to attribute a call to a different run.
• Nothing is recorded without a run id. Calls on inboxes that were never tagged add no events.

What is recorded, each with a timestamp, the inbox / identity / message involved, and the agent and project the key belongs to:

Events are kept for 30 days. Read a run back with your key:

curl https://otpbox.io/api/v1/runs/signup-8841   -H "authorization: Bearer $OTPBOX_KEY"

{
  "runId": "signup-8841",
  "startedAt": 1767225600000, "endedAt": 1767225603400, "durationMs": 3400,
  "status": "completed",
  "events": [
    { "type": "identity.created", "offsetMs": 0,    "identityId": "ident_...", "inboxId": "...", "detail": { "template": "us_customer" } },
    { "type": "email.received",   "offsetMs": 1210, "inboxId": "...", "messageId": "...", "detail": { "subject": "Your verification code" } },
    { "type": "otp.extracted",    "offsetMs": 1210, "messageId": "..." },
    { "type": "otp.read",         "offsetMs": 1880, "messageId": "..." },
    { "type": "inbox.deleted",    "offsetMs": 3400, "detail": { "reason": "deleted" } }
  ],
  "summary": { "inboxes": 1, "identities": 1, "emails": 1, "otpsExtracted": 1, "otpsRead": 1, "errors": 0, "emailToOtpMs": 670, "firstEmailMs": 1210 }
}

• GET /api/v1/runs/:runId returns the run for the calling key only; another key's run id returns 404 not_found. status is failed if any error event exists, otherwise completed once the inbox was deleted or a code was read, otherwise running.
• emailToOtpMs is the time from the first email to the first OTP read after it; firstEmailMs is the time from the first creation to the first email. Both are null until they can be measured.
• Organization members (not billing-only members) can browse recent runs, filter by agent, and open a timeline in the dashboard under Runs, or via GET /api/orgs/:id/runs?agentId=&days=&limit=&cursor= and GET /api/orgs/:id/runs/:runId with a dashboard session.

Idempotency keys

If a CI job retries a create call after a network timeout, it can end up with two inboxes. Send an Idempotency-Key header on POST /api/v1/inboxes or POST /api/v1/batches and a retry with the same key returns the original response instead of creating another resource.

curl -X POST https://otpbox.io/api/v1/inboxes \
  -H "authorization: Bearer $OTPBOX_KEY" \
  -H "idempotency-key: signup-test-run-8841" \
  -H "content-type: application/json" -d '{}'

• The key is 1–255 characters from A-Z a-z 0-9 _ . : - (UUIDs work well); anything else returns 400 invalid_idempotency_key. The header is optional.
• Keys are scoped to your API key and to the endpoint, so the same value can be reused against /inboxes and /batches without collision.
• Both successful and error responses are stored and replayed with the original status code. Records are kept for 24 hours.
• If a request with the same key is still in flight, the second one gets 409 idempotency_key_in_progress; retry after a moment.
• A replayed request still counts as one request against your quota. The identities routes do not read this header.

Webhooks

Get an HTTPS POST when something happens instead of polling. Webhooks belong to the API key that registered them and fire for that key's inboxes, identities and usage. Registering, listing and deleting them needs the webhook:manage scope (or a key with no scope restrictions).

Register

POST /api/v1/webhooks
{ "url": "https://your-app.example.com/webhooks/otpbox", "events": ["otp.extracted", "usage.approaching"] }

→ 201
{
  "id": "wh_...",
  "url": "https://your-app.example.com/webhooks/otpbox",
  "events": ["otp.extracted", "usage.approaching"],
  "secret": "...",
  "createdAt": 1790000000000
}

• url must start with https://, otherwise 400 { "error": "bad_url" }.
• events is a list from the catalog below. Unknown names are ignored; if none are valid you get 400 { "error": "bad_events", "validEvents": [...] }.
• The secret is returned once, only in this response. Store it now — you need it to verify signatures and it cannot be retrieved later.
• GET /api/v1/webhooks returns { webhooks: [{ id, url, events, status, createdAt }] } (never the secret). status is active or disabled.
• DELETE /api/v1/webhooks/:id returns { ok: true }, or 404 not_found.

Event catalog

Every delivery is a POST with content-type: application/json. The body is a JSON object whose event field names the event, followed by the fields shown below. The event name is also sent in the x-otpbox-event header.

Example payloads (timestamps are Unix milliseconds):

inbox.created

{ "event": "inbox.created", "inboxId": "a1b2c3d4e5f6", "address": "bold.quartz844@otpbox.io", "domain": "otpbox.io", "createdAt": 1790000000000, "expiresAt": 1790003600000 }

inbox.deleted

{ "event": "inbox.deleted", "inboxId": "a1b2c3d4e5f6", "address": "bold.quartz844@otpbox.io", "deletedAt": 1790000900000 }

inbox.expired

{ "event": "inbox.expired", "inboxId": "a1b2c3d4e5f6", "address": "bold.quartz844@otpbox.io", "expiresAt": 1790003600000, "expiredAt": 1790004200000 }

inbox.expiring

{ "event": "inbox.expiring", "inboxId": "a1b2c3d4e5f6", "address": "bold.quartz844@otpbox.io", "expiresAt": 1790003600000, "expiresInSeconds": 840 }

message.received

{ "event": "message.received", "inboxId": "a1b2c3d4e5f6", "messageId": "msg_...", "from": "noreply@example.com", "fromName": "Example", "subject": "Your verification code", "code": "482913", "link": null, "receivedAt": 1790000300000 }

otp.extracted

{ "event": "otp.extracted", "inboxId": "a1b2c3d4e5f6", "messageId": "msg_...", "from": "noreply@example.com", "fromName": "Example", "subject": "Your verification code", "code": "482913", "link": null, "receivedAt": 1790000300000 }

link.detected

{ "event": "link.detected", "inboxId": "a1b2c3d4e5f6", "messageId": "msg_...", "linkUrl": "https://example.com/verify?t=...", "linkHost": "example.com", "linkType": "verification", "receivedAt": 1790000300000 }

identity.created (single identity)

{ "event": "identity.created", "identityId": "ident_...", "template": "us_customer", "email": "bold.quartz844@otpbox.io", "country": "US", "createdAt": 1790000000000, "expiresAt": 1790003600000 }

identity.created (from /identities/bulk)

{ "event": "identity.created", "batchId": "idbatch_...", "template": "student", "requestedCount": 10, "createdCount": 10, "failedCount": 0, "createdAt": 1790000000000 }

identity.deleted

{ "event": "identity.deleted", "identityId": "ident_...", "inboxId": "a1b2c3d4e5f6", "email": "bold.quartz844@otpbox.io", "deletedAt": 1790000900000 }

usage.approaching and usage.exceeded

{ "event": "usage.approaching", "orgId": "org_...", "licenseId": "lic_...", "scope": "organization", "period": "2026-09", "used": 160, "limit": 200, "percent": 80 }

For an organization key the threshold is measured against the organization's pooled quota, and orgId and scope: "organization" are included; every key in the organization that has a subscribed webhook gets the event. For a personal key those two fields are omitted and used/limit are that key's own. usage.exceeded has the same shape with a percent of 100 or more.

Verify the signature

Each delivery carries an x-otpbox-signature header: the lowercase hex HMAC-SHA256 of the raw request body, keyed with the webhook's secret. Compute it over the exact bytes you received (before any JSON parsing) and compare in constant time. Reject anything that doesn't match.

// Node (Express)
import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhooks/otpbox', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = createHmac('sha256', process.env.OTPBOX_WEBHOOK_SECRET)
    .update(req.body) // Buffer: the raw body
    .digest('hex');
  const given = String(req.get('x-otpbox-signature') ?? '');

  const a = Buffer.from(expected);
  const b = Buffer.from(given);
  if (a.length !== b.length || !timingSafeEqual(a, b)) return res.status(401).end();

  const event = JSON.parse(req.body.toString('utf8'));
  if (event.event === 'otp.extracted') console.log('code:', event.code);
  res.status(200).end();
});

# Python (Flask)
import hashlib, hmac, os
from flask import Flask, abort, request

app = Flask(__name__)

@app.post('/webhooks/otpbox')
def otpbox_webhook():
    raw = request.get_data()  # bytes: the raw body
    expected = hmac.new(os.environ['OTPBOX_WEBHOOK_SECRET'].encode(), raw, hashlib.sha256).hexdigest()
    given = request.headers.get('x-otpbox-signature', '')

    if not hmac.compare_digest(expected, given):
        abort(401)

    event = request.get_json(force=True)
    if event['event'] == 'otp.extracted':
        print('code:', event['code'])
    return '', 200

The otpbox-sdk package ships the same check as verifyWebhookSignature(secret, rawBody, signatureHeader).

Delivery, retries and auto-disable

• A delivery succeeds when your endpoint answers with a 2xx status within 8 seconds. Anything else — another status, a timeout, a connection error — is a failure.
• The first attempt is sent immediately. A failed delivery is retried up to 5 attempts in total, waiting 5 minutes, 15 minutes, 1 hour and 4 hours after attempts 1 to 4. Retries are picked up by a job that runs every 15 minutes, so a retry can arrive up to 15 minutes later than these nominal delays. Each retry re-sends the identical body, so deduplicate on the payload (for example messageId) if your handler isn't idempotent.
• After 10 consecutive failed attempts the webhook is marked disabled (visible in GET /api/v1/webhooks) and stops receiving events; any successful delivery resets the counter. Once your endpoint is healthy again, re-enable it from the dashboard (Projects & keys → the key → Webhooks → Enable, then Send test to confirm) or register a new one with POST /api/v1/webhooks. The dashboard also sends a webhook.test event on demand and lets you redeliver any past delivery.
• Deliveries are not ordered. Answer quickly with a 2xx and do heavy work afterwards.

CI/CD: OTPs in GitHub Actions

The most common setup: a Playwright or Cypress E2E suite that signs up a real account and needs a real code to get past the OTP screen. The otpbox-sdk package (npm install otpbox-sdk) wraps the endpoints above in createInbox() / waitForOtp() / deleteInbox() so your workflow and test code don't hand-roll fetch calls.

# .github/workflows/e2e.yml
name: E2E
on: [push]
jobs:
  e2e:
    runs-on: ubuntu-latest
    env:
      OTPBOX_KEY: ${{ secrets.OTPBOX_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test

Add OTPBOX_KEY under repo Settings → Secrets and variables → Actions so it's injected as an env var and never checked into the workflow file.

Inside the test, create a real inbox, fill the signup form with its address, then block on the code:

import { test, expect } from '@playwright/test';
import { OTPBox } from 'otpbox-sdk';

test('sign up with a real OTP', async ({ page }) => {
  const client = new OTPBox({ apiKey: process.env.OTPBOX_KEY! });
  const inbox = await client.createInbox();

  await page.goto('https://your-app.example.com/signup');
  await page.fill('[name="email"]', inbox.address);
  await page.click('button[type="submit"]');

  const code = await client.waitForOtp(inbox.id, { timeoutMs: 20_000 });
  await page.fill('[name="otp"]', code);
  await page.click('button[type="submit"]');
  await expect(page.locator('text=Welcome')).toBeVisible();

  await client.deleteInbox(inbox.id);
});

A few CI-specific gotchas: never hardcode the key in the workflow YAML or commit it to the repo — always read it from a secret as above. Watch the free tier's 200 requests/month quota if the suite runs on every push or in a matrix — each inbox create/poll/delete counts against it, so a chatty suite on a busy repo can burn through it fast; upgrade or dedicate a key to CI if that happens. Call deleteInbox() in a finally/after-hook so failed runs don't leave orphaned inboxes around — though if you forget, the 15-minute expiry cron cleans them up automatically either way.

CI/CD: OTPs in GitLab CI

Same idea, run as a GitLab CI job: use the Playwright Docker image so playwright install isn't needed, inject the key as a masked CI/CD variable, and run the suite.

# .gitlab-ci.yml
e2e:
  stage: test
  image: mcr.microsoft.com/playwright:v1.48.0-jammy
  variables:
    OTPBOX_KEY: $OTPBOX_KEY
  script:
    - npm ci
    - npx playwright test

Add OTPBOX_KEY under your project's Settings → CI/CD → Variables, marked Masked and Protected so it never appears in job logs and only runs on protected branches.

The test code is identical to the Playwright example above: create an inbox with createInbox(), fill the signup form with inbox.address, block on waitForOtp(), then deleteInbox() in a finally block. The same gotchas apply — never print the key, watch the monthly quota on a busy pipeline, and let the 15-minute expiry cron clean up anything a failed job leaves behind.

CI/CD: OTPs in Jenkins

A declarative Jenkinsfile stage that installs Playwright's browsers and runs the suite, with the key pulled from Jenkins' own credential store rather than an env var set in the job config:

// Jenkinsfile
pipeline {
  agent any
  environment {
    OTPBOX_KEY = credentials('otpbox-key')
  }
  stages {
    stage('E2E') {
      steps {
        sh 'npm ci'
        sh 'npx playwright install --with-deps chromium'
        sh 'npx playwright test'
      }
    }
  }
}

Add otpbox-key under Manage Jenkins → Credentials as a Secret text credential — that's what credentials('otpbox-key') above resolves and masks in the console log.

Same test code as the GitHub Actions example: create an inbox, drive the signup form with its address, wait for the code, delete the inbox when done. Same gotchas too — nothing Jenkins-specific changes about the quota or cleanup story.

CI/CD: OTPs in CircleCI

A single job using the Playwright Docker image, with the key set as a project environment variable (CircleCI injects those into every job automatically, no explicit wiring needed):

# .circleci/config.yml
version: 2.1
jobs:
  e2e:
    docker:
      - image: mcr.microsoft.com/playwright:v1.48.0-jammy
    steps:
      - checkout
      - run: npm ci
      - run: npx playwright test
workflows:
  test:
    jobs:
      - e2e

Add OTPBOX_KEY under Project Settings → Environment Variables — it's then available as process.env.OTPBOX_KEY inside the test the same way it is locally, no environment: block in the config needed.

Test code, quota, and cleanup are exactly as described above: create the inbox, run the app's signup flow against its address, wait for the code, delete the inbox afterward.

MCP (for AI agents)

Quickest setup: otpbox.io/connect mints a free key and installs the server into Cursor or VS Code in one click, with copy-paste config for Claude Code, Claude Desktop, Codex, Windsurf and Gemini CLI.

The same key also works as an MCP server for agent/coding-assistant clients (Claude, Cursor, and others) that speak MCP. It is a remote (streamable HTTP) server at https://otpbox.io/mcp; authenticate with the same Authorization: Bearer header as the REST API:

{
  "mcpServers": {
    "otpbox": {
      "url": "https://otpbox.io/mcp",
      "headers": { "Authorization": "Bearer <your-key>" }
    }
  }
}

Exposes 13 tools — the same underlying data as /api/v1, callable directly by an agent mid-task. Inbox and message tools take the inbox id returned by create_test_inbox.

Each tool call counts as one request against your monthly quota, and tools enforce the same key scopes as REST. Failures come back as MCP tool errors (for example an over-quota call or a rate-limited call) rather than HTTP status codes, and a key that is missing, invalid, expired or inactive is rejected with 401/402 before any tool runs. Separately from the monthly quota, an agent is limited to 60 tool calls per minute per key.

Key scopes

A key can be restricted to a set of scopes when it is created in the organization dashboard (along with an optional key type, label and expiry date). A key created without scopes — including every personal free key — can use everything. A scoped key that calls something outside its scopes gets 403 { "error": "insufficient_scope", "required": "<scope>" }.

GET /api/v1/usage, GET /api/v1/metrics, GET /api/v1/batches/:id and the /api/v1/identities routes are not gated by a scope. Keys can also carry an expiry: an expired key gets 401 key_expired.

Rotating keys. Use Rotate on a key in the organization dashboard (owners and admins) to replace it without downtime. OTPBox mints a new key with the same label, scopes, key type, IP allowlist, agent and expiry, and shows its secret once. The old key keeps working for the overlap you choose — immediately, 15 minutes, 1 hour (the default) or 24 hours — then returns 401 key_expired (or 402 license_inactive if you chose immediately, which revokes it). The old and new key count as a single slot toward the per-organization key limit, and a key can be rotated once; rotate the new key to go again. The same action is available as POST /api/orgs/:id/projects/:pid/keys/:kid/rotate with { "graceMinutes": 0–1440 } from a signed-in dashboard session.

Rate limits and quota

Metered per monthly billing cycle, not a rolling window. The cycle starts on the day you signed up (for an organization key, the day the organization was created; for a personal free key, the day it was minted) and resets on that same day of each month, at UTC midnight — clamped to the last day of shorter months, so a cycle that starts on the 31st resets on Feb 28 or 29. Every authenticated /api/v1 request and every MCP tool call counts as one request — including reads, GET /api/v1/usage itself, and calls that end in an error such as 404. Organization keys share their organization's pooled quota (see Plans); a personal free key has its own. Exceeding your quota returns 429 with { "error": "quota_exceeded", "used": …, "limit": … } — nothing is ever charged for overage; upgrade or wait for the month to roll over. There's no CAPTCHA on /api/v1 or /mcp — the quota itself is the abuse control.

Check where you stand at any time:

GET /api/v1/usage
→ { "plan": "api_5k_monthly", "quotaLimit": 5000, "used": 812, "period": "2026-09-14", "resetsOn": "2026-10-14", "status": "active", "pooled": true }

For a finer breakdown than the single request counter, GET /api/v1/usage/events returns this key's billable events — api_request, mcp_call, inbox_created, message_received, otp_extracted and identity_created — as totals plus a series per UTC day (?days=30) or per hour (?granularity=hour, up to 7 days). Organization owners see the same numbers for the whole organization, broken down by project, on the dashboard's Usage page, with a CSV export for reconciliation. Only api_request and mcp_call count toward your plan's request quota; the rest are reported for visibility.

To be told before you hit the wall, subscribe a webhook to usage.approaching (80%) and usage.exceeded (100%). Two other limits are separate from the monthly quota: minting keys is limited to 5 per day per IP (429 rate_limited), and MCP is limited to 60 tool calls per minute per key.

Errors

Errors are JSON with an error code and an appropriate HTTP status; some carry extra fields. Authentication errors (401/402) are returned before anything is counted against your quota.

Need higher volume or an SLA?

Running a large test matrix, or want a dedicated plan with priority support? Tell us about your use case and we'll follow up. Current uptime: status page.

Questions: abuse@otpbox.io.

See also: guides (Playwright, Cypress, AI agents), pricing and the changelog.