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.
domain string
The part after the @, one of the domains from List domains. Default mailbox.maila.ai. It cannot change later.
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.
agent_mode string
What the inbox agent does with received email. off does nothing. classify adds a category, labels, a summary and the details your instructions ask for. reply does the same and may answer the sender once when your instructions say so.
firewall object
Which senders the inbox accepts and whom it may email, as inbound and outbound rules. Each has a default (allow or deny) and allow and deny patterns such as @example.com; inbound also has an action, quarantine or drop. Replaces the whole firewall; null removes it.
  • Role names such as postmaster, abuse and noreply are reserved.
  • An address is never given to another account. If it is taken, you get 409.
  • A domain that is not enabled for your account returns 403.
curl 
curl -X POST "https://api.maila.ai/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",
  "agent_mode": "off",
  "forwarding_addresses": [],
  "forwarded_count": 0,
  "forwarding_verification": "code",
  "firewall": null,
  "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 "https://api.maila.ai/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 "https://api.maila.ai/v1/inboxes/inb_mvdlh9c06724trm1" \
  -H "Authorization: Bearer $MAILA_API_KEY"
Response 
{
  "object": "inbox",
  "id": "inb_mvdlh9c06724trm1",
  "address": "support-agent@mailbox.maila.ai",
  "display_name": "Support Agent",
  "instructions": "Answer billing questions politely.",
  "categories": [],
  "status": "active",
  "agent_mode": "off",
  "forwarding_addresses": [],
  "forwarded_count": 0,
  "forwarding_verification": "code",
  "firewall": null,
  "created_at": 1792335167,
  "updated_at": 1792335167
}

Update an inbox #

PATCH /v1/inboxes/{inbox_id}

Changes the display name, instructions, categories, agent mode or firewall. 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.
agent_mode string
What the inbox agent does with received email. off does nothing. classify adds a category, labels, a summary and the details your instructions ask for. reply does the same and may answer the sender once when your instructions say so.
firewall object
Which senders the inbox accepts and whom it may email, as inbound and outbound rules. Each has a default (allow or deny) and allow and deny patterns such as @example.com; inbound also has an action, quarantine or drop. Replaces the whole firewall; null removes it.
curl 
curl -X PATCH "https://api.maila.ai/v1/inboxes/inb_mvdlh9c06724trm1" \
  -H "Authorization: Bearer $MAILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "display_name": "Billing Support" }'
Response 
{
  "object": "inbox",
  "id": "inb_mvdlh9c06724trm1",
  "address": "support-agent@mailbox.maila.ai",
  "display_name": "Support Agent",
  "instructions": "Answer billing questions politely.",
  "categories": [],
  "status": "active",
  "agent_mode": "off",
  "forwarding_addresses": [],
  "forwarded_count": 0,
  "forwarding_verification": "code",
  "firewall": null,
  "created_at": 1792335167,
  "updated_at": 1792335167
}

Disable an inbox #

POST /v1/inboxes/{inbox_id}/disable

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 POST "https://api.maila.ai/v1/inboxes/inb_mvdlh9c06724trm1/disable" \
  -H "Authorization: Bearer $MAILA_API_KEY"
Response 
{ "object": "inbox", "id": "inb_mvdlh9c06724trm1", "status": "disabled" }

Delete an inbox #

DELETE /v1/inboxes/{inbox_id}

Deletes the inbox and, in the background, all its threads, messages, attachments and files. This cannot be undone. Returns 202.

Path parameters

inbox_id string required
The inbox, for example inb_mvdlh9c06724trm1.
  • From the first call, every route treats the inbox as not found and it leaves your list.
  • The address stays reserved for you, and you can create it again at once as a new inbox. No other account can ever use it.
curl 
curl -X DELETE "https://api.maila.ai/v1/inboxes/inb_mvdlh9c06724trm1" \
  -H "Authorization: Bearer $MAILA_API_KEY"
Response 
{ "object": "inbox", "id": "inb_mvdlh9c06724trm1", "status": "deleting" }

List domains #

GET /v1/domains

Returns the domains you can create inboxes on: always mailbox.maila.ai, plus any other domain enabled for your account. This list is not paged.

curl 
curl "https://api.maila.ai/v1/domains" \
  -H "Authorization: Bearer $MAILA_API_KEY"
Response 
{
  "object": "list",
  "data": [
    { "object": "domain", "domain": "mailbox.maila.ai", "default": true }
  ],
  "next_cursor": null
}