Source: https://once-email.com/api Developer documentation Developer documentation API # 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/inboxes `` GET /v1/inboxes/{inboxId}/messages `` GET /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 SDKs]() View 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 bundle]() [SHA256SUMS]() 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 source]() [Read the practical guide]()