Zum Inhalt springen
NimbusNexus

Inboxes-API

Die REST-API hinter Inboxes: Inboxen, also Wegwerf-E-Mail-Adressen, anlegen und über ihre Adresse finden; sie umbenennen, deaktivieren und löschen; die Mail, die bei ihnen ankommt, lesen und durchsuchen, in einer Inbox oder über alle hinweg, und die Inboxen leeren; sowie Tarif und Verbrauch prüfen. Jede Operation unten zeigt ihren Request in der Sprache, die oben auf der Seite gewählt ist. Inboxes hat noch kein SDK, daher verwenden TypeScript, Python und Go den üblichen HTTP-Client der jeweiligen Sprache.

Aufrufe brauchen einen API-Key für Inboxes, den Sie in Ihrer Kontokonsole erstellen. Nachrichten über die API zu lesen erfordert einen bezahlten Tarif; der Schnellstart führt durch eine erste Inbox, und der Überblick behandelt das Durchsuchen von Nachrichten und das Lesen ihrer Header.

Base URL
https://inboxes.nimbusnexus.net
Authentication
Authorization: Bearer <API key>
Version
Inboxes 0.2.42 · 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

NameInTypeDescription
limitqueryinteger—
offsetqueryinteger—
addressquerystring | nullOnly the inbox with this email address (or its local part). 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

FieldTypeDescription
labelstring—
phraseboolean—
expires_in_minutesinteger | null—
transportstring—

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

NameInTypeDescription
inbox_id*pathstring—

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

NameInTypeDescription
inbox_id*pathstring—

Request body

FieldTypeDescription
labelstring | null—
statusstring | null—
phraseboolean | 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

NameInTypeDescription
inbox_id*pathstring—

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

One inbox's messages, newest first. Poll with since set to the newest received_at already seen; walk back with until. A search (q, or a header) continues with until set to the page's next_until; its offset skips messages before it reads.

Parameters

NameInTypeDescription
inbox_id*pathstring—
sincequerystring | null—
untilquerystring | null—
qquerystring | nullOnly messages containing this text, ignoring case, in the subject, the sender, a header (as `name: value`) or the body; `in` and `header` narrow where. A search reads at most 16 MiB of messages per call, newest first: when it stops before the oldest, `next_until` is set and `next_offset` is not.
inquery"all" | "subject" | "from" | "headers" | "body"Where `q` looks: `all`, or only `subject`, `from` (the sender, as the From header reads), `headers` (each as `name: value`) or `body` (the text body; for an HTML-only email, the text of its HTML).
headerquerystring | nullOnly this header's values, its name ignoring case; any of them when it arrived more than once. Without `q`, the messages that carry it at all.
extractquerystring | null—
limitqueryinteger—
offsetqueryinteger—

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

NameInTypeDescription
inbox_id*pathstring—

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

NameInTypeDescription
inbox_id*pathstring—
message_id*pathstring—
extractquerystring | 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.

More

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.

A search (q, or a header) reads the same stream and continues with until set to the page's next_until, exactly as on the per-inbox route.

Parameters

NameInTypeDescription
sincequerystring | null—
untilquerystring | null—
qquerystring | nullOnly messages containing this text, ignoring case, in the subject, the sender, a header (as `name: value`) or the body; `in` and `header` narrow where. A search reads at most 16 MiB of messages per call, newest first: when it stops before the oldest, `next_until` is set and `next_offset` is not.
inquery"all" | "subject" | "from" | "headers" | "body"Where `q` looks: `all`, or only `subject`, `from` (the sender, as the From header reads), `headers` (each as `name: value`) or `body` (the text body; for an HTML-only email, the text of its HTML).
headerquerystring | nullOnly this header's values, its name ignoring case; any of them when it arrived more than once. Without `q`, the messages that carry it at all.
extractquerystring | null—
limitqueryinteger—
offsetqueryinteger—

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.

More

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

NameInTypeDescription
sincequerystring | null—
untilquerystring | null—
limitqueryinteger—
offsetqueryinteger—

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"