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.
category string
Only threads with this category.
status string
open, archived or quarantined. quarantined lists the threads the inbox firewall held back, which the default list leaves out.
curl 
curl "https://api.maila.ai/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 "https://api.maila.ai/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

labels string[]
Replaces the labels. Up to 20.
category string
Sets the category. An empty string clears it.
status string
open or archived. A new reply reopens an archived thread. Either value releases a quarantined thread into the normal list.
read boolean
true marks the thread read; false marks it unread.
curl 
curl -X PATCH "https://api.maila.ai/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" }'

Delete a thread #

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

Deletes the thread with its messages, attachments and stored files, and removes its messages from search. This cannot be undone.

Path parameters

inbox_id string required
The inbox, for example inb_mvdlh9c06724trm1.
thread_id string required
The thread, for example thr_mvdlijmoxjmnbx5g.
curl 
curl -X DELETE "https://api.maila.ai/v1/inboxes/inb_mvdlh9c06724trm1/threads/thr_mvdlijmoxjmnbx5g" \
  -H "Authorization: Bearer $MAILA_API_KEY"
Response 
{ "object": "thread", "id": "thr_mvdlijmoxjmnbx5g", "deleted": true }

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 "https://api.maila.ai/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 \
  "https://api.maila.ai/v1/inboxes/inb_mvdlh9c06724trm1/threads/thr_mvdlijmoxjmnbx5g/items/att_mvdlij8sh1qgdw02/content" \
  -H "Authorization: Bearer $MAILA_API_KEY"