Skip to content

Email

Threads and messages

Incoming email is grouped into threads automatically: a reply joins the thread of the message it answers. Each thread holds its messages and their attachments.

List threads #

GET /v1/inboxes/{inbox_id}/threads

Returns an inbox's threads, most recent activity first.

Path parameters

inbox_id string required
The inbox, for example inb_mvdlh9c06724trm1.

Query parameters

limit integer
Results per page, 1–100. Default 20.
cursor string
The next_cursor from the previous page.
status string
open or archived.
category string
Only threads with this category.
curl 
curl "$MAILA_API_URL/v1/inboxes/inb_mvdlh9c06724trm1/threads?status=open" \
  -H "Authorization: Bearer $MAILA_API_KEY"
Response 
{
  "object": "list",
  "data": [
    {
      "object": "thread",
      "id": "thr_mvdlijmoxjmnbx5g",
      "inbox_id": "inb_mvdlh9c06724trm1",
      "subject": "Question about my invoice",
      "participants": ["jane@example.com", "support-agent@mailbox.maila.ai"],
      "snippet": "Hi, I was charged twice for October…",
      "message_count": 2,
      "unread_count": 1,
      "last_message_at": 1792335223,
      "category": null,
      "labels": [],
      "status": "open"
    }
  ],
  "next_cursor": null
}

Get a thread #

GET /v1/inboxes/{inbox_id}/threads/{thread_id}

Returns the thread with all its messages, oldest first, and each message's attachments.

Path parameters

inbox_id string required
The inbox, for example inb_mvdlh9c06724trm1.
thread_id string required
The thread, for example thr_mvdlijmoxjmnbx5g.
  • direction is in for received email and out for email you sent.
  • status is received, sent, failed, bounced or complained.
  • spam_verdict and virus_verdict show the result of scanning received email: PASS, FAIL or GRAY.
  • text holds up to 100 KB; text_truncated tells you when there is more. Download the full email with Download content.
curl 
curl "$MAILA_API_URL/v1/inboxes/inb_mvdlh9c06724trm1/threads/thr_mvdlijmoxjmnbx5g" \
  -H "Authorization: Bearer $MAILA_API_KEY"
Response 
{
  "object": "thread",
  "id": "thr_mvdlijmoxjmnbx5g",
  "subject": "Question about my invoice",
  "message_count": 1,
  "messages": [
    {
      "object": "message",
      "id": "msg_mvdliiuwzfsa7ngv",
      "direction": "in",
      "from": { "address": "jane@example.com", "name": "Jane Doe" },
      "to": ["support-agent@mailbox.maila.ai"],
      "subject": "Question about my invoice",
      "text": "Hi, I was charged twice for October…",
      "has_html": true,
      "status": "received",
      "spam_verdict": "PASS",
      "virus_verdict": "PASS",
      "received_at": 1792335188,
      "attachments": [
        {
          "object": "attachment",
          "id": "att_mvdlij8sh1qgdw02",
          "filename": "invoice-october.pdf",
          "content_type": "application/pdf",
          "size": 48213
        }
      ]
    }
  ]
}

Update a thread #

PATCH /v1/inboxes/{inbox_id}/threads/{thread_id}

Organizes a thread. Send only the fields you want to change.

Path parameters

inbox_id string required
The inbox, for example inb_mvdlh9c06724trm1.
thread_id string required
The thread, for example thr_mvdlijmoxjmnbx5g.

Body

read boolean
true marks the thread read; false marks it unread.
status string
open or archived. A new reply reopens an archived thread.
labels string[]
Replaces the labels. Up to 20.
category string
Sets the category. An empty string clears it.
curl 
curl -X PATCH "$MAILA_API_URL/v1/inboxes/inb_mvdlh9c06724trm1/threads/thr_mvdlijmoxjmnbx5g" \
  -H "Authorization: Bearer $MAILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "read": true, "labels": ["billing"], "status": "archived" }'

Get a message or attachment #

GET /v1/inboxes/{inbox_id}/threads/{thread_id}/items/{item_id}

Returns one message (msg_…) with its attachments, or one attachment (att_…).

Path parameters

inbox_id string required
The inbox, for example inb_mvdlh9c06724trm1.
thread_id string required
The thread, for example thr_mvdlijmoxjmnbx5g.
item_id string required
A message or attachment id.
curl 
curl "$MAILA_API_URL/v1/inboxes/inb_mvdlh9c06724trm1/threads/thr_mvdlijmoxjmnbx5g/items/msg_mvdliiuwzfsa7ngv" \
  -H "Authorization: Bearer $MAILA_API_KEY"

Download content #

GET /v1/inboxes/{inbox_id}/threads/{thread_id}/items/{item_id}/content

Redirects to a download link that works for 5 minutes. For an attachment you get the file. For a message you get the complete original email (.eml), or its HTML body with ?format=html.

Path parameters

inbox_id string required
The inbox, for example inb_mvdlh9c06724trm1.
thread_id string required
The thread, for example thr_mvdlijmoxjmnbx5g.
item_id string required
A message or attachment id.

Query parameters

format string
html for a message's HTML body.
  • Use -L so curl follows the redirect.
curl 
curl -L -o invoice-october.pdf \
  "$MAILA_API_URL/v1/inboxes/inb_mvdlh9c06724trm1/threads/thr_mvdlijmoxjmnbx5g/items/att_mvdlij8sh1qgdw02/content" \
  -H "Authorization: Bearer $MAILA_API_KEY"