Skip to content

Email

Inboxes

An inbox is an email address on mailbox.maila.ai that your agent can receive and send from.

Create an inbox #

POST /v1/inboxes

Creates an inbox at <local_part>@mailbox.maila.ai. It can receive email right away. Returns 201.

Body

local_part string
The part before the @. Lowercase letters, digits, ., _ and -, up to 64 characters. Leave it out for a random address.
display_name string
The sender name recipients see. Up to 100 characters.
instructions string
Notes for your agent about this inbox. Up to 10,000 characters.
categories string[]
Up to 20 category names you use to organize threads.
  • Role names such as postmaster, abuse and noreply are reserved.
  • An address belongs to one inbox for good. If it is taken, you get 409.
curl 
curl -X POST "$MAILA_API_URL/v1/inboxes" \
  -H "Authorization: Bearer $MAILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "support-agent",
    "display_name": "Support Agent",
    "instructions": "Answer billing questions politely."
  }'
Response 
{
  "object": "inbox",
  "id": "inb_mvdlh9c06724trm1",
  "address": "support-agent@mailbox.maila.ai",
  "display_name": "Support Agent",
  "instructions": "Answer billing questions politely.",
  "categories": [],
  "status": "active",
  "created_at": 1792335167,
  "updated_at": 1792335167
}

List inboxes #

GET /v1/inboxes

Returns your inboxes, oldest first.

Query parameters

limit integer
Results per page, 1–100. Default 20.
cursor string
The next_cursor from the previous page.
curl 
curl "$MAILA_API_URL/v1/inboxes?limit=20" \
  -H "Authorization: Bearer $MAILA_API_KEY"
Response 
{
  "object": "list",
  "data": [
    { "object": "inbox", "id": "inb_mvdlh9c06724trm1", "address": "support-agent@mailbox.maila.ai", "status": "active" }
  ],
  "next_cursor": null
}

Get an inbox #

GET /v1/inboxes/{inbox_id}

Returns one inbox.

Path parameters

inbox_id string required
The inbox, for example inb_mvdlh9c06724trm1.
curl 
curl "$MAILA_API_URL/v1/inboxes/inb_mvdlh9c06724trm1" \
  -H "Authorization: Bearer $MAILA_API_KEY"

Update an inbox #

PATCH /v1/inboxes/{inbox_id}

Changes the display name, instructions or categories. Send only the fields you want to change. The address cannot change.

Path parameters

inbox_id string required
The inbox, for example inb_mvdlh9c06724trm1.

Body

display_name string
Up to 100 characters.
instructions string
Up to 10,000 characters.
categories string[]
Replaces the list. Up to 20 names.
curl 
curl -X PATCH "$MAILA_API_URL/v1/inboxes/inb_mvdlh9c06724trm1" \
  -H "Authorization: Bearer $MAILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "display_name": "Billing Support" }'

Disable an inbox #

DELETE /v1/inboxes/{inbox_id}

Stops the inbox from receiving and sending email. Its threads stay readable, and the address stays reserved for you; it is never given to anyone else.

Path parameters

inbox_id string required
The inbox, for example inb_mvdlh9c06724trm1.
curl 
curl -X DELETE "$MAILA_API_URL/v1/inboxes/inb_mvdlh9c06724trm1" \
  -H "Authorization: Bearer $MAILA_API_KEY"
Response 
{ "object": "inbox", "id": "inb_mvdlh9c06724trm1", "status": "disabled" }