An inbox in your code.
One less thing to build.

Prefer typed source? Download the TypeScript file. Go, PHP, Java, C# and Ruby are planned. They are not available yet.

THE RIGHT KEY FOR EACH REQUEST

No global API key to get started.

Creating an inbox on the default or a public domain needs no authentication. Each inbox is private: use its own token for every read or delete request.

Authenticated HTTP requests use Authorization: Bearer TOKEN. JSON requests use Content-Type: application/json. SDKs set these headers for you.

FROM DNS TO YOUR FIRST DELIVERY

Connect a domain in order.

For an existing public domain, read GET /api/config and use its ID when creating an inbox. To connect a private domain, follow these steps or use Your domains.

1. Create a workspace and save its token. Add your domain with POST /api/v1/domains.
2. Publish the returned TXT proof and configure Cloudflare Email Routing for this domain or subdomain. Apply the MX records Cloudflare provides.
3. Call the domain’s /verify endpoint. Check that ownershipVerified and mxVerified are both true.
4. Generate a receiver key. Download the Cloudflare receiver and follow its README to deploy the Worker and set the domain’s catch-all routing rule. Use the returned inbound path, hostname and receiver key.
5. Send a real email from another provider to testAddress. This tests the complete mail route; its contents are discarded.
6. Read the domain until status is ready. Create an inbox with its domainId and your workspace key. Use the newly returned inbox token to read mail.

Keep the ownership TXT record published. DNS is rechecked on active use after ten minutes, and failed checks block new creation or delivery until verification succeeds. Reissuing a receiver key requires a new connection test.

HANDLE THE UNHAPPY PATH

Know what to retry.

HTTP errors use an error object instead of data. The SDKs raise InbiniError with the status and code. Network failures may raise a native error.

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": {
    "code": "INBOX_EXPIRED",
    "message": "This inbox has expired. Create a new one."
  }
}

Poll for the message you actually need.

Create an inbox, record your test start time, trigger your application’s email, and poll with that timestamp. The example below starts a new polling window; set after to the saved test start time if the email was already triggered.

import { InbiniError } from './inbini.mjs';

// With an existing inbox object:
try {
  const code = await inbox.waitForCode({
    from: '[email protected]',
    subject: 'verification',
    after: new Date().toISOString(),
    timeout: 60_000, // milliseconds
  });
  console.log(code);
} catch (error) {
  if (error instanceof InbiniError) {
    console.error(error.status, error.code, error.message);
    // error.retryAfter is in seconds.
  } else {
    throw error;
  }
}

The wait helpers poll once per second and honor Retry-After when throttled. Ordinary one-shot SDK calls raise the error so your code can decide what to retry. Use waitForMessage / wait_for_message for the full message, or waitForLink / wait_for_link for its first HTTP(S) link.

Choose the expiry your workflow needs.

There are no fixed quotas for inbox creation, requests per inbox or messages per inbox. Inboxes still expire: use a positive duration such as 45m, 2h or 7d. The default is one hour, and resuming an inbox never extends it.

Message contents are plain text and are deleted on expiry or when you delete them. Operational receipt metadata is retained permanently, as described on the privacy page.