Examples in

Inboxes API

The REST API behind Inboxes: create disposable email addresses and HTTP request bins, read what they receive, and check your plan and usage. Every operation below shows its request in the language picked at the top of the page. Inboxes has no SDK yet, so TypeScript, Python and Go use each language's usual HTTP client.

Calls take an API key for Inboxes, created in your account console. Reading messages over the API needs a paid plan; the quickstart walks through a first address.

Base URL: https://inboxes.nimbusnexus.net
Authentication: Authorization: Bearer <API key>
Version: Inboxes 0.2.31 · OpenAPI spec

Before the examples

The examples read your API key from INBOXES_API_KEY.

Shell

export INBOXES_API_KEY="<your-api-key>"

Inboxes

GET/v1/inboxes

List Inboxes

Parameters

Name	In	Type	Description
limit	query	integer	—
offset	query	integer	—
address	query	string \| null	Only the inbox with this email address, bin slug or bin URL. Returns at most one item, or none.

Responses

200Successful Response
401error.code = unauthorized
402error.code = workspace_suspended
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X GET "https://inboxes.nimbusnexus.net/v1/inboxes" \
  -H "Authorization: Bearer $INBOXES_API_KEY"

POST/v1/inboxes

Create Inbox

Request body

Field	Type	Description
label	string	—
phrase	boolean	—
expires_in_minutes	integer \| null	—
transport	"email" \| "http"	—

Responses

201Successful Response
401error.code = unauthorized
402error.code = quota_exceeded
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X POST "https://inboxes.nimbusnexus.net/v1/inboxes" \
  -H "Authorization: Bearer $INBOXES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

GET/v1/inboxes/{inbox_id}

Read Inbox

Parameters

Name	In	Type	Description
inbox_id*	path	string	—

Responses

200Successful Response
401error.code = unauthorized
402error.code = workspace_suspended
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X GET "https://inboxes.nimbusnexus.net/v1/inboxes/<inbox_id>" \
  -H "Authorization: Bearer $INBOXES_API_KEY"

PATCH/v1/inboxes/{inbox_id}

Patch Inbox

Parameters

Name	In	Type	Description
inbox_id*	path	string	—

Request body

Field	Type	Description
label	string \| null	—
status	string \| null	—
phrase	boolean \| null	—

Responses

200Successful Response
401error.code = unauthorized
402error.code = not_entitled
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X PATCH "https://inboxes.nimbusnexus.net/v1/inboxes/<inbox_id>" \
  -H "Authorization: Bearer $INBOXES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE/v1/inboxes/{inbox_id}

Delete Inbox

Parameters

Name	In	Type	Description
inbox_id*	path	string	—

Responses

204Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X DELETE "https://inboxes.nimbusnexus.net/v1/inboxes/<inbox_id>" \
  -H "Authorization: Bearer $INBOXES_API_KEY"

Messages

GET/v1/inboxes/{inbox_id}/messages

List Messages

Parameters

Name	In	Type	Description
inbox_id*	path	string	—
since	query	string \| null	—
until	query	string \| null	—
extract	query	string \| null	—
limit	query	integer	—
offset	query	integer	—

Responses

200Successful Response
401error.code = unauthorized
402error.code = not_entitled
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X GET "https://inboxes.nimbusnexus.net/v1/inboxes/<inbox_id>/messages" \
  -H "Authorization: Bearer $INBOXES_API_KEY"

DELETE/v1/inboxes/{inbox_id}/messages

Empty Inbox

Parameters

Name	In	Type	Description
inbox_id*	path	string	—

Responses

200Successful Response
401error.code = unauthorized
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X DELETE "https://inboxes.nimbusnexus.net/v1/inboxes/<inbox_id>/messages" \
  -H "Authorization: Bearer $INBOXES_API_KEY"

GET/v1/inboxes/{inbox_id}/messages/{message_id}

Read Message

Parameters

Name	In	Type	Description
inbox_id*	path	string	—
message_id*	path	string	—
extract	query	string \| null	—

Responses

200Successful Response
401error.code = unauthorized
402error.code = not_entitled
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X GET "https://inboxes.nimbusnexus.net/v1/inboxes/<inbox_id>/messages/<message_id>" \
  -H "Authorization: Bearer $INBOXES_API_KEY"

GET/v1/messages

List All Messages

Every message in the workspace, newest first, across every one of its addresses.

WHAT THIS IS FOR. Until now the only way to see what had arrived ANYWHERE was to walk the addresses one at a time — the console showed one inbox and you switched between them. Asking the question by fanning out over the per-inbox route is not an option and never was: at Pro's 25 addresses on the console's 3s poll it is 500 requests a minute from a single tab, the same arithmetic that already forced arrival counts to be aggregated server-side for the addresses list rather than derived per row.

NOT A REPLACEMENT FOR THE PER-INBOX ROUTE. That one stays the way to read ONE address, and it is what a CI poller should use — narrower, cheaper, and it 404s when its address is gone, which is the signal a script wants. This is the human question ("what has arrived") rather than the machine one ("did the mail I am waiting for land yet").

THE GATE IS THE CREDENTIAL, NOT THE ROUTE — require_read_api, exactly as its sibling does it. A browser session reads on every plan including free; only a minted API key is charged for programmatic access. Gating the route instead is how the read API shipped the first time, and it made free unusable in a way no test caught: the dashboard necessarily calls the same endpoint a script does, so mail arrived, parsed, stored, and could be looked at by nobody.

Each row carries its own inbox_id already, so nothing new goes on the wire — a client joins the address string from the inbox list it has loaded anyway rather than having it denormalised onto every message, which would be a second copy of a value that can be renamed.

Parameters

Name	In	Type	Description
since	query	string \| null	—
until	query	string \| null	—
extract	query	string \| null	—
limit	query	integer	—
offset	query	integer	—

Responses

200Successful Response
401error.code = unauthorized
402error.code = not_entitled
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X GET "https://inboxes.nimbusnexus.net/v1/messages" \
  -H "Authorization: Bearer $INBOXES_API_KEY"

Plan and usage

GET/v1/audit

List Audit

The workspace's control-plane history, newest first, narrowable by time.

THE WINDOW IS NOT A CONVENIENCE HERE. This route had no filter of any kind, and nothing ever deletes an AuditLog row — retention.py purges messages and released inboxes and leaves the log alone, on purpose, because a compliance trail that expires is not one. So the only way to reach an entry from six months ago was to page offset through every mutation since, and the log only grows. since/until is the door: an admin names the window they are investigating and reads it from the front.

Same strict-since / inclusive-until pair as the message routes, and for the same reasons — see service.messages_query. The statement lives in service.audit_query rather than here so that the UTC normalisation those bounds depend on has exactly one spelling in this service.

Parameters

Name	In	Type	Description
since	query	string \| null	—
until	query	string \| null	—
limit	query	integer	—
offset	query	integer	—

Responses

200Successful Response
401error.code = unauthorized
402error.code = workspace_suspended
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X GET "https://inboxes.nimbusnexus.net/v1/audit" \
  -H "Authorization: Bearer $INBOXES_API_KEY"

GET/v1/plan

Read Plan

Responses

200Successful Response
401error.code = unauthorized
402error.code = workspace_suspended
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X GET "https://inboxes.nimbusnexus.net/v1/plan" \
  -H "Authorization: Bearer $INBOXES_API_KEY"

GET/v1/usage

Read Usage

Responses

200Successful Response
401error.code = unauthorized
402error.code = workspace_suspended
403error.code = forbidden
404error.code = not_found
409error.code = conflict
413error.code = payload_too_large
422error.code = validation_error
429error.code = rate_limited
500error.code = internal_error

Example

curl -X GET "https://inboxes.nimbusnexus.net/v1/usage" \
  -H "Authorization: Bearer $INBOXES_API_KEY"

Edit this page on GitHub