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 token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
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. Branch on the error code: conflict — 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; agent_category_conflict — the agent_id names an identity already bound to the other kind of mail (one agent identity sends either transactional or marketing mail, never both; an identity dormant for 30 days may rebind). (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 request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.
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 token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
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 request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.
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 token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
ErrorDocument
|
| 404 |
The resource does not exist, or it belongs to another account. The two cases return the same status, error code and detail by design, so the error document does not confirm that an identifier is in use.
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 request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.
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 token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
ErrorDocument
|
| 404 |
The resource does not exist, or it belongs to another account. The two cases return the same status, error code and detail by design, so the error document does not confirm that an identifier is in use.
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. Branch on the error code: conflict — 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; agent_category_conflict — the agent_id names an identity already bound to the other kind of mail (one agent identity sends either transactional or marketing mail, never both; an identity dormant for 30 days may rebind). (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 request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.
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 token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
ErrorDocument
|
| 404 |
The resource does not exist, or it belongs to another account. The two cases return the same status, error code and detail by design, so the error document does not confirm that an identifier is in use.
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 request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.
ErrorDocument
|