Inboxes

Create an inbox

Create an inbox and get back a live, addressable email identity. Every field is optional: omit `username` and a readable random address is generated on the shared domain. Supply a `client_id` for idempotency — repeating a create with the same `client_id` returns the existing inbox (`200`) instead of creating a duplicate.

POST
/inboxes

Create an inbox and get back a live, addressable email identity. Every field is optional: omit username and a readable random address is generated on the shared domain. Supply a client_id for idempotency — repeating a create with the same client_id returns the existing inbox (200) instead of creating a duplicate.

Authorization

x-api-key<token>

The per-tenant API key. Sent as the x-api-key request header. The key is tenant-scoped.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Create-inbox body. Every field is optional — an empty body creates an inbox with a random address.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/inboxes" \  -H "Content-Type: application/json" \  -d '{}'
{  "inbox_id": "string",  "email": "user@example.com",  "display_name": "string",  "client_id": "string",  "metadata": {    "property1": "string",    "property2": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}
{  "inbox_id": "string",  "email": "user@example.com",  "display_name": "string",  "client_id": "string",  "metadata": {    "property1": "string",    "property2": "string"  },  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}
{  "name": "string",  "message": "string"}
{  "name": "string",  "message": "string"}
{  "name": "string",  "message": "string"}
{  "name": "validation",  "errors": {    "property1": "string",    "property2": "string"  }}
{  "name": "string",  "message": "string"}

Resolve the authenticated tenant GET

Echoes the tenant the presented API key resolves to. Useful as an "is my key valid?" check. Returns `401` if the key is missing/invalid.

Delete an inbox DELETE

Hard-delete an inbox and its stored mail; the address is quarantined for a cooling-off period before it can be reused. An unknown, already-deleted, or cross-tenant id returns not-found — a delete is never silently successful on a missing inbox.