Disposable Email API

The OpenInbox disposable email API lets your code create throwaway inboxes on demand, receive real inbound messages, and read or delete them — all over a small, predictable REST interface. It is built for automated testing (signup, OTP, password-reset, magic-link flows), QA environments, and any product feature that needs a temporary address. Below is the full surface: authentication, every endpoint, response shapes, and a complete example — all matching the live API.

What you can do

• Create a disposable inbox — POST /api/inbox
• List the emails an inbox has received — GET /api/inbound/api/emails?inboxEmail=<email>
• Read a single email in full — GET /api/emails/:id
• Delete an inbox — DELETE /api/inbox/:id
• Extend an inbox’s lifetime — POST /api/inbox/:id/extend

Authentication

The base URL is https://api.openinbox.io/api. Creating an inbox requires no authentication, so you can generate throwaway addresses freely. Reading received emails is a premium feature: send your key in an X-API-KEY header. Generate a key in your account settings (it is also returned by POST /api/user/api-key for logged-in users). Keep it server-side and out of version control.

Create an inbox

A single POST returns a fresh inbox. No body or auth is required.

curl -s -X POST https://api.openinbox.io/api/inbox

# Response (201):
# {
#   "id": "abc123",
#   "email": "[email protected]",
#   "expiresAt": "2026-04-07T12:00:00Z",
#   "createdAt": "2026-04-07T11:00:00Z",
#   "isActive": true
# }

Receive emails

Poll the inbox by address. Pass your key in the X-API-KEY header; page and limit are optional (default limit 20, max 100). Each email includes the full textBody and htmlBody — there is no separate fetch needed to read the body.

curl -s "https://api.openinbox.io/api/inbound/api/[email protected]&page=1&limit=20" \
  -H "X-API-KEY: $OPENINBOX_API_KEY"

# Response (200):
# {
#   "emails": [
#     {
#       "id": "660e8400-...",
#       "from": "[email protected]",
#       "subject": "Verify your email",
#       "textBody": "Your code is 482910",
#       "htmlBody": "<p>Your code is 482910</p>",
#       "receivedAt": "2026-04-07T11:05:00Z",
#       "isRead": false
#     }
#   ],
#   "total": 1,
#   "page": 1,
#   "limit": 20,
#   "totalPages": 1
# }

Read a single email, delete, and extend

Fetch one email by id, delete an inbox when you are done (they also auto-expire), or extend an inbox that needs to live longer than its default hour.

# Read one email in full
curl -s https://api.openinbox.io/api/emails/EMAIL_ID \
  -H "X-API-KEY: $OPENINBOX_API_KEY"

# Delete an inbox (optional — inboxes auto-expire)
curl -s -X DELETE https://api.openinbox.io/api/inbox/abc123

# Extend an inbox's lifetime
curl -s -X POST https://api.openinbox.io/api/inbox/abc123/extend

A complete example (Node.js)

Create an inbox, then poll for the verification email and pull the OTP out of textBody with a regex. The same shape works in any language — only the HTTP client changes.

const BASE = 'https://api.openinbox.io/api';
const KEY = process.env.OPENINBOX_API_KEY;

// 1. Create a disposable inbox (no auth)
const inbox = await fetch(`${BASE}/inbox`, { method: 'POST' }).then((r) => r.json());
console.log('Inbox:', inbox.email);

// 2. (Trigger your app so it emails inbox.email …)

// 3. Poll for the email (X-API-KEY required)
let otp;
for (let i = 0; i < 15; i++) {
  await new Promise((r) => setTimeout(r, 2_000));
  const { emails } = await fetch(
    `${BASE}/inbound/api/emails?inboxEmail=${encodeURIComponent(inbox.email)}`,
    { headers: { 'X-API-KEY': KEY } },
  ).then((r) => r.json());
  if (emails.length > 0) {
    otp = emails[0].textBody.match(/\b\d{4,8}\b/)?.[0];
    break;
  }
}
console.log('OTP:', otp);

Plans & rate limits

Creating inboxes is free. Reading received emails over the API is part of the paid tiers — Pro and Business (and the 7-Day Pass) include higher daily request limits suited to CI/CD. The free tier is rate-limited to prevent abuse. See the pricing page for current limits per plan.