Developer API

Disposable email,
in your code.

Generate temporary inboxes, receive emails, and verify signups programmatically. Pay only for the requests you make.

Get started — 10 free credits Read the docs

Simple auth

One Bearer token. Generate as many keys as you need on the dashboard.

Pay-as-you-go

Credits never expire. No subscriptions. Top up only when you run out.

Built for testing

Long-poll endpoint, custom usernames, 5 domains, instant inbox generation.

Simple credit packs

One credit = one billable request. Generating inboxes is free.

Starter

10,000 credits

$0.0005/credit · never expires

Developer

Best value

$20

50,000 credits

$0.0004/credit · never expires

Scale

$50

150,000 credits

$0.00033/credit · never expires

Every account gets 10 free credits to try the API. No card required.

API reference

Everything you need to integrate the API. Copy-paste ready.

Base URL & authentication

All endpoints live under:

https://vanishinbox.com/api/v1

Authenticate every request with a Bearer token from your API keys page:

Authorization: Bearer vib_live_YOUR_KEY

Pricing & metering

One credit equals one billable API request. Generating addresses, listing domains, account info, and clearing inboxes are free. Fetching email contents costs one credit per call.

Every response includes the current balance in headers:

X-Credits-Remaining: 9842
X-Credits-Used: 1

If you run out of credits, requests return 402 Payment Required. Top up on the billing page. Credits never expire.

Rate limits

Each API key is limited to 120 requests per minute across all endpoints. The limit is per key, so if you need higher throughput you can create additional keys on the keys page.

Every response includes your current limit state:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1748419260

When you exceed the limit, requests return 429 Too Many Requests with a Retry-After header telling you how many seconds to wait. Tight polling loops should use the /wait endpoint instead — it's the same cost but only counts as one request against the limit.

Endpoints

GET/meFree

Returns the authenticated account's credit balance and key metadata. Use this to verify your key works.

Request

curl https://vanishinbox.com/api/v1/me \
  -H "Authorization: Bearer vib_live_YOUR_KEY"

Response

{
  "credits": 9842,
  "key": {
    "id": "2cfdd221-0515-472e-8ed1-9e83d9a4e1ac",
    "name": "Production",
    "prefix": "vib_live_Jo4"
  }
}

POST/inbox/generateFree

Generates a fresh disposable inbox address. The address is reserved as soon as the first email arrives and lives for 10 minutes from then. All body fields are optional.

Request body

{
  "domain":   "fommie.com" | "random",  // optional, default 'random'
  "username": "my-test-flow"            // optional, auto-generated if omitted
}

Request

curl -X POST https://vanishinbox.com/api/v1/inbox/generate \
  -H "Authorization: Bearer vib_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "random"}'

Response

{
  "address": "[email protected]",
  "username": "leanmink654",
  "domain": "fommie.com",
  "expires_in_seconds": 600
}

GET/domainsFree

Lists all domains available through the API. Use this to avoid hardcoding the domain list — we may add or rotate domains over time.

Request

curl https://vanishinbox.com/api/v1/domains \
  -H "Authorization: Bearer vib_live_YOUR_KEY"

Response

{
  "domains": [
    { "name": "fommie.com" },
    { "name": "whoopza.org" },
    { "name": "fommie.online" },
    { "name": "fommie.store" },
    { "name": "whoopza.store" }
  ]
}

GET/inbox/{address}1 credit

Fetches all emails received at the address. Returns an empty array if nothing has arrived yet. The 10-minute expiry timer starts when the first email is received.

Request

curl https://vanishinbox.com/api/v1/inbox/[email protected] \
  -H "Authorization: Bearer vib_live_YOUR_KEY"

Response

{
  "address": "[email protected]",
  "emails": [
    {
      "id": "...",
      "from": "[email protected]",
      "subject": "Verify your email",
      "html": "<p>Click here...</p>",
      "text": "Click here...",
      "receivedAt": "2026-05-21T08:15:00.000Z"
    }
  ],
  "expires_in_seconds": 580
}

GET/inbox/{address}/wait1 credit

Long-polls for new emails. Returns immediately if emails already exist, otherwise blocks up to 30 seconds waiting for one. Use this instead of tight polling — same cost, but far more efficient for both of us.

Query params

timeout=30  // optional, max 60

Request

curl "https://vanishinbox.com/api/v1/inbox/[email protected]/wait?timeout=30" \
  -H "Authorization: Bearer vib_live_YOUR_KEY"

Response

{
  "address": "[email protected]",
  "emails": [...],
  "timed_out": false,
  "expires_in_seconds": 580
}

DELETE/inbox/{address}Free

Immediately clears the inbox and expires the address.

Request

curl -X DELETE https://vanishinbox.com/api/v1/inbox/[email protected] \
  -H "Authorization: Bearer vib_live_YOUR_KEY"

Response

{
  "address": "[email protected]",
  "cleared": true
}

Custom usernames

Pass username in the generate request to pick your own local part. Useful when you want a predictable address for test fixtures.

curl -X POST https://vanishinbox.com/api/v1/inbox/generate \
  -H "Authorization: Bearer vib_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "signup-test-42", "domain": "fommie.com"}'

# → [email protected]

Rules:

3 to 64 characters
Lowercase letters, digits, dot, hyphen, underscore
Must start and end with a letter or digit
No consecutive dots

Usernames aren't reserved — if two people generate the same address, they share the inbox. For test isolation, include a unique component (timestamp, UUID fragment) in your username.

Errors

Errors come back as JSON with a type and message:

{
  "error": {
    "type": "insufficient_credits",
    "message": "You have no credits remaining. Top up your balance to continue.",
    "topup_url": "https://vanishinbox.com/dashboard/billing"
  }
}

400invalid_requestmalformed input

401unauthorizedmissing or invalid API key

402insufficient_creditsout of credits

429rate_limit_exceededtoo many requests; honour Retry-After

500internal_errorserver failure; credit is refunded automatically

End-to-end example

A complete signup-verification flow in Node.js:

const API_KEY = process.env.VANISHINBOX_KEY
const BASE = 'https://vanishinbox.com/api/v1'
const headers = { Authorization: `Bearer ${API_KEY}` }

// 1. Generate a fresh inbox
const { address } = await fetch(`${BASE}/inbox/generate`, {
  method: 'POST',
  headers,
}).then(r => r.json())

// 2. Use it to sign up wherever
await signupOnSomeService({ email: address })

// 3. Wait for the verification email
const { emails } = await fetch(
  `${BASE}/inbox/${address}/wait?timeout=30`,
  { headers }
).then(r => r.json())

// 4. Extract the verification link
const verifyLink = emails[0].html.match(/href="([^"]+verify[^"]*)"/)[1]
console.log('Click here:', verifyLink)

Ready to start?

Get my API key

Disposable email,in your code.

Simple auth

Pay-as-you-go

Built for testing

Simple credit packs

Starter

Developer

Scale

API reference

Base URL & authentication

Pricing & metering

Rate limits

Endpoints

Custom usernames

Errors

End-to-end example

Ready to start?

Disposable email,
in your code.