import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.agents.inbox(
  "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.get_agent_inbox(
    "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
)
print(result)

curl 'https://api.mails.ai/v1/agents/agt_01JZX8K3M9Q4P7VN2YB6RTDC0E/inbox' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails agents inbox hello

{
  "name": "mails_agents_inbox",
  "arguments": {
    "agent": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E"
  }
}

{
  "agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "email": "jordan@example.com",
  "unread_count": 0,
  "folders": {
    "inbox": { "threads": 0, "unread": 0 },
    "archive": { "threads": 0, "unread": 0 },
    "spam": { "threads": 0, "unread": 0 },
    "trash": { "threads": 0, "unread": 0 },
    "sent": { "threads": 0, "unread": 0 }
  },
  "labels": [
    {
      "id": "<id>",
      "name": "<name>",
      "color": "<color>",
      "threads": 0,
      "unread": 0
    }
  ],
  "last_message_at": "2026-10-04T12:00:00.000Z"
}

200  The agent's inbox summary.
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
409  Conflict — duplicate resource, an in-progress
     idempotent request, a draft or scheduled message
     that started sending while it was being changed, or
     a thread deleted for good while one of its messages
     is being sent (duplicate_resource); or an agent
     name more than one agent has (agent_name_conflict:
     use the agent's id); or a status change on an
     archived agent, since archiving cannot be undone
     (agent_archived).
500  Internal server error.

Inbox summary

Unread count, thread and unread counts per folder and per label, and the time of the latest message.

GET/v1/agents/{id}/inboxscope · read

import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.agents.inbox(
  "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.get_agent_inbox(
    "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
)
print(result)

curl 'https://api.mails.ai/v1/agents/agt_01JZX8K3M9Q4P7VN2YB6RTDC0E/inbox' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails agents inbox hello

{
  "name": "mails_agents_inbox",
  "arguments": {
    "agent": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E"
  }
}

{
  "agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "email": "jordan@example.com",
  "unread_count": 0,
  "folders": {
    "inbox": { "threads": 0, "unread": 0 },
    "archive": { "threads": 0, "unread": 0 },
    "spam": { "threads": 0, "unread": 0 },
    "trash": { "threads": 0, "unread": 0 },
    "sent": { "threads": 0, "unread": 0 }
  },
  "labels": [
    {
      "id": "<id>",
      "name": "<name>",
      "color": "<color>",
      "threads": 0,
      "unread": 0
    }
  ],
  "last_message_at": "2026-10-04T12:00:00.000Z"
}

200  The agent's inbox summary.
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
409  Conflict — duplicate resource, an in-progress
     idempotent request, a draft or scheduled message
     that started sending while it was being changed, or
     a thread deleted for good while one of its messages
     is being sent (duplicate_resource); or an agent
     name more than one agent has (agent_name_conflict:
     use the agent's id); or a status change on an
     archived agent, since archiving cannot be undone
     (agent_archived).
500  Internal server error.

Path Parameters

idstringrequired

Agent id or name.

Response

agent_idstring

The agent's id (agt_…), also when the path named it by name.

emailstring

The agent's address: <name>@<slug>.mails.ai, or <name>@<your domain> for an agent created on a custom domain.

unread_countinteger

Unread threads in the inbox folder.

foldersobject

Thread and unread counts for each of the five folders: inbox, archive, spam, trash and sent. Every folder is present, with zeros when it is empty.

Show propertiesHide properties

inboxobject

The agent's threads in the inbox folder; both counts are 0 when there are none.

Show propertiesHide properties

threadsinteger

How many of the agent's threads are in this folder, test and live mail alike.

unreadinteger

How many of them are unread, counted in the key's own mode: a live key counts threads that hold live mail, a test key threads that hold only test mail.

archiveobject

The agent's threads in the archive folder; both counts are 0 when there are none.

Show propertiesHide properties

threadsinteger

How many of the agent's threads are in this folder, test and live mail alike.

unreadinteger

How many of them are unread, counted in the key's own mode: a live key counts threads that hold live mail, a test key threads that hold only test mail.

spamobject

The agent's threads in the spam folder; both counts are 0 when there are none.

Show propertiesHide properties

threadsinteger

How many of the agent's threads are in this folder, test and live mail alike.

unreadinteger

How many of them are unread, counted in the key's own mode: a live key counts threads that hold live mail, a test key threads that hold only test mail.

trashobject

The agent's threads in the trash folder; both counts are 0 when there are none.

Show propertiesHide properties

threadsinteger

How many of the agent's threads are in this folder, test and live mail alike.

unreadinteger

How many of them are unread, counted in the key's own mode: a live key counts threads that hold live mail, a test key threads that hold only test mail.

sentobject

The agent's threads in the sent folder; both counts are 0 when there are none.

Show propertiesHide properties

threadsinteger

How many of the agent's threads are in this folder, test and live mail alike.

unreadinteger

How many of them are unread, counted in the key's own mode: a live key counts threads that hold live mail, a test key threads that hold only test mail.

labelsobject[]

Every label on the agent's inbox threads, with thread and unread counts.

Show propertiesHide properties

idstring | null

Null for a name with no label object behind it.

namestring

The label's name: the label object's own spelling when one matches, ignoring case; otherwise as the threads carry it.

colorstring | null

The matching label object's colour, a palette name. Null for a name with no label object behind it.

threadsinteger

How many of the agent's inbox threads carry this label, test and live mail alike.

unreadinteger

How many of those threads are unread, counted in the key's own mode like a folder's unread.

last_message_atstring | null

When a message last joined any of the agent's threads, in any folder, trash included. Null when the agent has no threads.

Was this page helpful?