Disposable Email API: A Getting-Started Guide for Developers

A disposable email API lets a test create an isolated address, wait for incoming mail, and read a verification message without touching a developer's personal inbox. With Inboxto, the current public API uses https://inboxto.app/api as its base URL, accepts Bearer API keys, and exposes endpoints for creating addresses, listing messages, and fetching a single message. API access is a Premium feature; the free plan is better suited to manual inbox checks.

This guide builds the smallest useful workflow: create one persistent test address, trigger your own staging signup, poll with a deadline, then fetch the matching message body.

What the Inboxto API currently exposes

The public Inboxto API documentation lists these core operations:

Task	Method and path	Permission shown in docs
Create an address	POST /v1/addresses	addresses:write
List addresses	GET /v1/addresses	addresses:read
List inbox messages	GET /v1/messages?address=...	messages:read
Fetch one message	GET /v1/messages/:id	messages:read
Delete one message	DELETE /v1/messages/:id	messages:delete
Read and delete the newest unread message	POST /v1/messages/pop	messages:read, messages:delete

The base URL goes before each path, so listing messages uses:

https://inboxto.app/api/v1/messages?address=your-address

Use the regular list and detail endpoints while getting started. The pop operation is queue-like and deletes the message it returns, which makes it a poor default when a failed test still needs evidence.

For the broader testing architecture, including custom domains and browser-test isolation, read Inboxto for developers.

Authentication and rate limits

Create an API key in your Inboxto account settings, then send it in every request:

Authorization: Bearer ib_your_api_key

Keep the key in a secret manager or environment variable. Do not put it in source code, a committed .env file, a URL, or test output. The public documentation says requests are limited to 100 per hour by default and that responses include rate-limit headers. Treat that number as the current default, not a permanent promise; check the live documentation before sizing a CI workload.

First-hand public API check, August 24, 2026: We reviewed the live /docs page and made an unauthenticated read-only request to GET https://inboxto.app/api/v1/addresses. It returned HTTP 401 with Missing or invalid Authorization header, matching the documented Bearer requirement. We did not use or transmit an Inboxto account key during that check.

API access and custom domains are currently listed under Premium at $6.99/mo or $67.99/yr. The free plan currently includes three persistent addresses for manual use, but not API access. Pricing and limits can change, so verify the product page before committing a team workflow.

Create your first persistent test address

The create-address endpoint requires an address. Use an address on a domain configured for your account; do not copy example.com literally.

curl -X POST https://inboxto.app/api/v1/addresses \
  -H "Authorization: Bearer $INBOXTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "signup-20260824@your-configured-domain.example",
    "display_name": "Signup test",
    "type": "custom",
    "is_primary": false
  }'

The documented success response wraps the created object in { "success": true, "data": ... } and includes an ID, the address, its type, and created_at.

Inboxto addresses are persistent: the address does not disappear after a short countdown. That matters when the same test account needs a password reset or re-verification in a later run. Message retention is separate from address persistence, so retain only the mail your test genuinely needs.

If the distinction between a temporary inbox and a persistent privacy address is new, start with what temporary email is and how it works.

List messages and fetch one body

After your application sends mail, query the exact recipient address. The list endpoint supports limit, offset, and an unread filter; its documented default limit is 20.

curl -G https://inboxto.app/api/v1/messages \
  -H "Authorization: Bearer $INBOXTO_API_KEY" \
  --data-urlencode "address=signup-20260824@your-configured-domain.example" \
  --data-urlencode "limit=10" \
  --data-urlencode "unread=true"

Each listed message includes fields such as id, from, to, subject, text_body, html_body, unread, and received_at. Once you have the matching ID, fetch the detail record:

curl https://inboxto.app/api/v1/messages/message-uuid \
  -H "Authorization: Bearer $INBOXTO_API_KEY"

The detail response additionally documents headers and attachments. Validate recipient, expected sender, subject, and timestamp before extracting a code or opening a link. A six-digit string from an old message is not proof that the current signup worked. The user-facing guide to finding the right verification email covers the same trust checks from the inbox side.

First end-to-end Node.js script

This example uses the built-in fetch available in current Node.js releases. It creates a named address, asks a placeholder function to trigger your own staging system, and polls for up to 60 seconds. Replace the configured domain and triggerStagingSignup implementation with your legitimate test environment.

const API_BASE = 'https://inboxto.app/api';
const API_KEY = process.env.INBOXTO_API_KEY;
const address = `signup-${Date.now()}@your-configured-domain.example`;

if (!API_KEY) throw new Error('INBOXTO_API_KEY is required');

async function api(path, options = {}) {
  const response = await fetch(`${API_BASE}${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  const body = await response.json();
  if (!response.ok) {
    throw new Error(`Inboxto API ${response.status}: ${body.message || body.error}`);
  }
  return body.data;
}

async function triggerStagingSignup(recipient) {
  // Call your own staging signup endpoint or browser flow here.
  console.log(`Trigger staging signup for ${recipient}`);
}

await api('/v1/addresses', {
  method: 'POST',
  body: JSON.stringify({
    address,
    display_name: 'Automated signup test',
    type: 'custom',
    is_primary: false
  })
});

await triggerStagingSignup(address);

const deadline = Date.now() + 60_000;
let match;

while (Date.now() < deadline) {
  const messages = await api(
    `/v1/messages?address=${encodeURIComponent(address)}&limit=10&unread=true`
  );
  match = messages.find(
    (message) => message.to === address && message.subject.includes('Verify')
  );
  if (match) break;
  await new Promise((resolve) => setTimeout(resolve, 5_000));
}

if (!match) throw new Error(`Verification email did not arrive for ${address}`);

const message = await api(`/v1/messages/${encodeURIComponent(match.id)}`);
console.log({ id: message.id, from: message.from, subject: message.subject });

Do not log text_body, html_body, reset URLs, or one-time codes by default. CI logs are often more widely visible and retained longer than the inbox itself.

Poll without wasting the rate limit

The example waits five seconds between reads and stops after 60 seconds. That is intentionally boring. A tight loop can exhaust the documented default limit, while a fixed multi-minute sleep makes every successful test slow.

For a larger suite:

• create a unique address per parallel test so messages cannot cross-match
• inspect rate-limit headers instead of assuming remaining capacity
• add jitter when many workers start together
• stop after a clear deadline and report the last known delivery stage
• reuse a persistent address only when the test specifically covers recovery or re-verification

Start with one critical signup flow before adding every notification test. If manual testing is enough, the free UI is simpler and costs no API quota. If you are still comparing inbox categories and providers, use the temporary and anonymous email comparison rather than choosing on API availability alone.

Scope and safety limits

Inboxto is a receive-only email product. It does not send mail, provide SMS numbers, or promise that an external platform will accept a disposable domain. Use the API for mail you are authorized to test: your staging signup, QA notifications, verification flows, and controlled custom domains.

Do not point test automation at real customer accounts or use it to evade another service's signup controls. For high-value production accounts, keep recovery in a strongly controlled company or personal mailbox.

Next step

The minimum disposable email API workflow is now complete: authenticate, create a persistent address, trigger one authorized email, poll with a deadline, validate the message, and fetch its body only when needed.

Review the live Inboxto API docs, create a scoped key in account settings, and begin with one staging verification path. For manual testing before you need automation, open Inboxto and use a free persistent inbox.

Sources checked

• Inboxto API documentation
• Inboxto official homepage and pricing

The public API documentation, unauthenticated API boundary, and product pricing page were checked on August 24, 2026. Endpoint contracts, limits, permissions, and plans may change; treat the live documentation as authoritative.