Inboxes
Inbox management operations.
POST
/inboxes
Create an inbox
Creates a managed inbound mailbox at an address on one of your sending domains, so mail sent
to it is received, parsed, and exposed through the API (and as inbound_email.received
webhooks).
The first inbox on a domain provisions the inbound MX record and routing
automatically; subsequent inboxes reuse it. If the address is ambiguous — the same domain
name exists in more than one region under your account — the request is rejected with 422
and you should register a region-distinct subdomain.
Inboxes are governed by the domain scopes: requires the domains:write scope.
Request body
application/vnd.api+json
— CreateInboxRequestDocument
|
Attribute
|
Type
|
Description
|
|---|---|---|
name
required
|
string | |
address
required
|
string |
POST /inboxes
curl -X POST https://api.minimailer.app/inboxes \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json" \ -H "Content-Type: application/vnd.api+json" \ -d '{"data":{"type":"inboxes","attributes":{"name":"...","address":"..."}}}'
Responses
|
Status
|
Description
|
|---|---|
| 201 |
Inbox created.
InboxDocument
|
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The authenticated token does not have permission to perform this action.
ErrorDocument
|
| 415 |
The request Content-Type must be application/vnd.api+json, with no media type parameters other than profile (ext is rejected — no JSON:API extensions are supported — as is any other parameter such as charset).
ErrorDocument
|
| 422 |
The request document failed validation.
ValidationErrorDocument
|
| 409 |
The request conflicts with the endpoint or current state: the document's resource type does not match the endpoint, its id does not match the resource being updated, or an idempotency key was reused with a different payload. (Creating with a client-generated id and updating relationships on an endpoint that does not support them return 403 instead.)
ErrorDocument
|
| 406 |
The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
ErrorDocument
|
| 429 |
The caller exceeded the API rate limit.
ErrorDocument
|
GET
/inboxes
List inboxes
Returns the authenticated user's inbound mailboxes, newest first, with the JSON:API
sort, include, and sparse fields parameters. Requires the domains:read
scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
sort
|
query | Comma-separated sort fields; prefix a field with - for descending, e.g. sort=-created_at,name. Defaults to newest-first. Only allow-listed fields are accepted; an unsupported sort returns 400. |
include
|
query | Comma-separated related resources to embed in the response included member (JSON:API compound documents). Example: include=records,webhooks. Nested paths use dot notation, max depth 2. Relationships not declared by the resource, or over-deep paths, return 400. |
fields
|
query | Per-type sparse fieldsets. Example: fields[domains]=name,status restricts the returned attributes for that type. The type must be present in the document and each field must be a known attribute, otherwise 400 is returned. |
page
|
query | Cursor-based pagination, e.g. page[cursor]=eyJpZCI6...&page[size]=50. The cursor is an opaque token issued by the API — take it from the response's links.next / links.prev URLs or meta.next_cursor / meta.prev_cursor; never construct one. size defaults to 25 and is silently capped at 100 (out-of-range or non-numeric values fall back to the default). An invalid or expired cursor falls back to the first page; a cursor replayed with a different sort than it was issued under returns 400; unknown page members such as page[number] return 400. Follow links.next until it is null (or meta.has_more is false) to traverse a collection; links.first restarts traversal. Link URLs carry these parameters URL-encoded (page%5Bcursor%5D=...). |
GET /inboxes
curl -X GET https://api.minimailer.app/inboxes \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json"
Responses
|
Status
|
Description
|
|---|---|
| 400 |
The include or fields query parameter is not supported (unknown relationship, over-deep include, or unknown sparse-fieldset type or field).
ErrorDocument
|
| 200 |
Inboxes retrieved.
InboxCollectionDocument
|
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The authenticated token does not have permission to perform this action.
ErrorDocument
|
| 406 |
The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
ErrorDocument
|
| 429 |
The caller exceeded the API rate limit.
ErrorDocument
|
GET
/inboxes/{inbox}
Show an inbox
Returns a single inbound mailbox owned by the authenticated user, including its address and
configuration. Requires the domains:read scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
include
|
query | Comma-separated related resources to embed in the response included member (JSON:API compound documents). Example: include=records,webhooks. Nested paths use dot notation, max depth 2. Relationships not declared by the resource, or over-deep paths, return 400. |
fields
|
query | Per-type sparse fieldsets. Example: fields[domains]=name,status restricts the returned attributes for that type. The type must be present in the document and each field must be a known attribute, otherwise 400 is returned. |
inbox
required
|
path | The inbox identifier. |
GET /inboxes/{inbox}
curl -X GET https://api.minimailer.app/inboxes/{inbox} \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json"
Responses
|
Status
|
Description
|
|---|---|
| 400 |
The include or fields query parameter is not supported (unknown relationship, over-deep include, or unknown sparse-fieldset type or field).
ErrorDocument
|
| 200 |
Inbox retrieved.
InboxDocument
|
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The authenticated token does not have permission to perform this action.
ErrorDocument
|
| 404 |
The requested resource could not be found.
ErrorDocument
|
| 406 |
The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
ErrorDocument
|
| 429 |
The caller exceeded the API rate limit.
ErrorDocument
|
PATCH
/inboxes/{inbox}
Update an inbox
Updates the mutable settings of an inbound mailbox owned by the authenticated user. The
inbox address is immutable — create a new inbox to receive at a different address. Requires
the domains:write scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
inbox
required
|
path | The inbox identifier. |
Request body
application/vnd.api+json
— UpdateInboxRequestDocument
|
Attribute
|
Type
|
Description
|
|---|---|---|
name
|
string | |
address
|
string |
PATCH /inboxes/{inbox}
curl -X PATCH https://api.minimailer.app/inboxes/{inbox} \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json" \ -H "Content-Type: application/vnd.api+json" \ -d '{"data":{"type":"inboxes","attributes":{"name":"...","address":"..."}}}'
Responses
|
Status
|
Description
|
|---|---|
| 200 |
Inbox updated.
InboxDocument
|
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The authenticated token does not have permission to perform this action.
ErrorDocument
|
| 404 |
The requested resource could not be found.
ErrorDocument
|
| 415 |
The request Content-Type must be application/vnd.api+json, with no media type parameters other than profile (ext is rejected — no JSON:API extensions are supported — as is any other parameter such as charset).
ErrorDocument
|
| 422 |
The request document failed validation.
ValidationErrorDocument
|
| 409 |
The request conflicts with the endpoint or current state: the document's resource type does not match the endpoint, its id does not match the resource being updated, or an idempotency key was reused with a different payload. (Creating with a client-generated id and updating relationships on an endpoint that does not support them return 403 instead.)
ErrorDocument
|
| 406 |
The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
ErrorDocument
|
| 429 |
The caller exceeded the API rate limit.
ErrorDocument
|
DELETE
/inboxes/{inbox}
Delete an inbox
Deletes an inbound mailbox owned by the authenticated user and stops receiving mail at its
address. Inbound emails already received and stored remain retrievable. Requires the
domains:write scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
inbox
required
|
path | The inbox identifier. |
DELETE /inboxes/{inbox}
curl -X DELETE https://api.minimailer.app/inboxes/{inbox} \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json"
Responses
|
Status
|
Description
|
|---|---|
| 204 | Inbox deleted. |
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The authenticated token does not have permission to perform this action.
ErrorDocument
|
| 404 |
The requested resource could not be found.
ErrorDocument
|
| 406 |
The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
ErrorDocument
|
| 429 |
The caller exceeded the API rate limit.
ErrorDocument
|