Developer documentationAPI

Once Email API

Public developer documentation for automated email testing: authentication, quotas, errors, and safe-use rules.

Documentation is public. API key creation and live calls are not open to the public. The workflow below is only for testers who already have explicit API access authorization and valid credentials.
Authentication

Send Authorization: Bearer oe_live_… with every request. A key is shown once; keep it in a secrets manager and never place it in browser code, logs, or Git.

Authorization: Bearer oe_live_your_key
Workflow for authorized testers
  1. Proceed only with explicitly authorized API access and already issued, valid credentials with the minimum necessary permissions. Store them in a process secret facility; without this access, stop at reviewing the documentation and downloads. Create a temporary inbox and retain its inbox ID.
  2. Ask your test system to send mail to that address.
  3. Poll the message list with backoff; avoid rapid empty polling.
  4. Read the target message, complete assertions, then delete the inbox.

Private Beta endpoints

POST /v1/inboxesGET /v1/inboxes/{inboxId}/messagesGET /v1/inboxes/{inboxId}/messages/{uid}GET /v1/inboxes/{inboxId}/messages/{uid}/attachments/{cid}DELETE /v1/inboxes/{inboxId}

Status codes

400

Invalid request

401

Missing or invalid key

403

Plan or resource denied

404

Resource not found

413

Response or attachment too large

429

Rate or monthly quota reached

503

Temporary service failure

Client availability

Open-source prerelease candidates are available for TypeScript, Python, Java, Go, .NET, PHP, and Ruby. Native CI passed on Linux, macOS, and Windows; language registry releases are not available yet.

Billing status

The Developer plan uses a monthly Stripe subscription and monthly API allowance. Stored-value recharge is not offered. Live checkout remains closed until payment and refund gates pass.

Acceptable use

Use the API only on systems you are authorized to test. Spam, policy evasion, account abuse, monitoring other people’s communications, and long-term personal-data storage are prohibited. Message bodies and attachments do not enter account history.

The API is entering production readiness
Public documentation and prerelease downloads do not grant API access. API key creation and live calls are not publicly open.
View SDKsView pricing

API Demo

Cross-platform safe example

For owned or authorized test systems; runs on Windows, Linux, and macOS with Node.js 20+.

node demos/api/authorized-workflow.mjs
ONCE_EMAIL_API_KEY <- process secret facility
create inbox -> list messages -> finally delete inbox
Open full demo

Complete usage guide

Download the versioned local bundle

Use only an application you own or are explicitly authorized to test. Once Email receives mail only; it does not send mail or automate third-party registrations.

Documentation and source are public. API calls remain controlled. SDKs and the Skill are versioned prerelease downloads, not language-registry releases. Public documentation and prerelease downloads do not grant API access. API key creation and live calls are not publicly open.

Open SHA256SUMS before extracting the file.

Download bundleSHA256SUMS

Exact local starting point

node demos/api/authorized-workflow.mjs

From download to a clean first run

  1. Confirm ownership or explicit authorization; use local, test, or staging only.
  2. Proceed only with explicitly authorized API access and already issued, valid credentials with the minimum necessary permissions. Store them in a process secret facility; without this access, stop at reviewing the documentation and downloads.
  3. Download, verify, extract, and read README.md plus LOCAL-USAGE.md.
  4. Run the Node.js 20+ demo, then trigger one uniquely marked email from the authorized system.
  5. Poll with bounded backoff and one deadline; read only the unique match.
  6. Delete the inbox in finally and report cleanup failure separately.

Failure and recovery

Keep 400, 401, 403, 404, 413, 429, and 503 distinct. Timeout, ambiguity, extraction, assertion, and cleanup are also different failures. Retry only within one deadline and never turn a dependency failure into an empty inbox.

Browse public sourceRead the practical guide