title: "Inboxes" description: "Create, list, search, read, update, pause and delete MachineMail inboxes, and check whether an address is available. The inbox_id is the email address." canonical: "https://machinemail.dev/docs/reference/api/inboxes"

Inboxes

Create, list, search, read, update, pause and delete MachineMail inboxes, and check whether an address is available. The inbox_id is the email address.

Source: https://machinemail.dev/docs/reference/api/inboxes

List Inboxes

GET /v0/inboxes

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_read.

Query parameters

Response

200 A page of inboxes (application/json)

Each item of inboxes is a Inbox:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "inboxes": [
    {
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
      "inbox_id": "agent@machinemail.dev",
      "email": "agent@machinemail.dev",
      "display_name": "Support Agent",
      "client_id": "my-client-id",
      "status": "active",
      "metadata": {
        "key": "value"
      },
      "updated_at": "2026-10-01T12:00:00.000Z",
      "created_at": "2026-10-01T12:00:00.000Z",
      "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
      "ephemeral": false,
      "ttl_seconds": 1,
      "expires_at": "2026-10-01T12:00:00.000Z",
      "created_by": "api"
    }
  ]
}

Create Inbox

POST /v0/inboxes

ephemeral: true without ttl_seconds creates an inbox with a one hour TTL (3600 seconds).

An organization can have at most 1,000 inboxes on the shared domain; past that the API returns 403. Add your own domain for more. Inbox-scoped credentials cannot create inboxes (403).

A taken address returns 409, and so does a reserved one: role and brand names on the shared domain, and {slug}@ on the shared domain, which only the organization with that slug can create (agent- followed by 16 or more hex digits is reserved the same way).

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_create.

Request body

Content type: application/json.

Response

200 An inbox with this client_id already exists; it is returned unchanged. (application/json)

201 Created (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/inboxes" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "agent",
  "display_name": "Support Agent"
}'

{
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "inbox_id": "agent@machinemail.dev",
  "email": "agent@machinemail.dev",
  "display_name": "Support Agent",
  "client_id": "my-client-id",
  "status": "active",
  "metadata": {
    "key": "value"
  },
  "updated_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "ephemeral": false,
  "ttl_seconds": 1,
  "expires_at": "2026-10-01T12:00:00.000Z",
  "created_by": "api"
}

Check Inbox Availability

GET /v0/inboxes/availability

Whether username@domain can be created by this organization now. Never a 4xx for a bad name: reason says why it is not available.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_read.

Query parameters

Response

200 Availability of the address (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes/availability" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "available": false,
  "email": "agent@machinemail.dev",
  "reason": "invalid_username",
  "message": "string"
}

Search Inboxes

GET /v0/inboxes/search

Inboxes whose address or display name contains q (case-insensitive), newest first. Searches the newest 500 inboxes in scope; the response has truncated: true when there were more. Not ranked by relevance.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_read.

Query parameters

Response

200 A page of matching inboxes (application/json)

Each item of inboxes is a Inbox:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes/search?q=invoice" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Get Inbox

GET /v0/inboxes/{inbox_id}

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_read.

Path parameters

Response

200 The inbox (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update Inbox

PATCH /v0/inboxes/{inbox_id}

Fields you omit are unchanged. To pause an inbox, set status to paused; set it back to active to resume.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_update.

Path parameters

Request body

Content type: application/json.

Response

200 The updated inbox (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "Support Agent"
}'

Delete Inbox

DELETE /v0/inboxes/{inbox_id}

Deletes the inbox with its messages, attachments, threads and drafts. Inbox-scoped credentials cannot delete their own inbox (403).

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_delete.

Path parameters

Response

200 Deleted (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}

List Inboxes in Pod

GET /v0/pods/{pod_id}/inboxes

Same as List Inboxes (GET /v0/inboxes), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_read.

Path parameters

Query parameters

Response

200 A page of inboxes (application/json)

Each item of inboxes is a Inbox:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Create Inbox in Pod

POST /v0/pods/{pod_id}/inboxes

Same as Create Inbox (POST /v0/inboxes), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_create.

Path parameters

Request body

Content type: application/json.

Response

200 An inbox with this client_id already exists; it is returned unchanged. (application/json)

201 Created (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "username": "agent",
  "display_name": "Support Agent"
}'

Check Inbox Availability in Pod

GET /v0/pods/{pod_id}/inboxes/availability

Same as Check Inbox Availability (GET /v0/inboxes/availability), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_read.

Path parameters

Query parameters

Response

200 Availability of the address (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/availability" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "available": false,
  "email": "agent@machinemail.dev",
  "reason": "invalid_username",
  "message": "string"
}

Search Inboxes in Pod

GET /v0/pods/{pod_id}/inboxes/search

Same as Search Inboxes (GET /v0/inboxes/search), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_read.

Path parameters

Query parameters

Response

200 A page of matching inboxes (application/json)

Each item of inboxes is a Inbox:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/search?q=invoice" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Get Inbox in Pod

GET /v0/pods/{pod_id}/inboxes/{inbox_id}

Same as Get Inbox (GET /v0/inboxes/{inbox_id}), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_read.

Path parameters

Response

200 The inbox (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update Inbox in Pod

PATCH /v0/pods/{pod_id}/inboxes/{inbox_id}

Same as Update Inbox (PATCH /v0/inboxes/{inbox_id}), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_update.

Path parameters

Request body

Content type: application/json.

Response

200 The updated inbox (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X PATCH "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "Support Agent"
}'

Delete Inbox in Pod

DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}

Same as Delete Inbox (DELETE /v0/inboxes/{inbox_id}), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: inbox_delete.

Path parameters

Response

200 Deleted (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

{
  "ok": true
}