---
title: "Inbox summary"
method: GET
path: "/v1/agents/{id}/inbox"
tags: ["Agents"]
---

# Inbox summary

`GET /v1/agents/{id}/inbox`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/agents/{id}/inbox`
- Auth: HTTP bearer

**Requires scope:** `read`. Unread count, thread and unread counts per folder and per label, and the time of the latest message.

## Path parameters

- `id` string, required

## Response `200`

The agent's inbox summary.

- InboxSummary
  - `agent_id` string, required: The agent's id (`agt_…`), also when the path named it by name.
  - `email` string, email, required: The agent's API address: `<name>@<slug>.mails.ai`, or `<name>@<your domain>` for an agent created on a custom domain. A `<slug>.mails.ai` address is not an inbox: people write to the agent at its `receiving_address`, `<name>.<slug>@in.mails.ai`.
  - `unread_count` integer, required: Unread threads in the inbox folder.
  - `folders` object, required: 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.
    - `inbox` object, required: The agent's threads in the `inbox` folder; both counts are 0 when there are none.
      - `threads` integer, required: How many of the agent's threads are in this folder, test and live mail alike.
      - `unread` integer, required: 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.
    - `archive` object, required: The agent's threads in the `archive` folder; both counts are 0 when there are none.
      - `threads` integer, required: How many of the agent's threads are in this folder, test and live mail alike.
      - `unread` integer, required: 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.
    - `spam` object, required: The agent's threads in the `spam` folder; both counts are 0 when there are none.
      - `threads` integer, required: How many of the agent's threads are in this folder, test and live mail alike.
      - `unread` integer, required: 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.
    - `trash` object, required: The agent's threads in the `trash` folder; both counts are 0 when there are none.
      - `threads` integer, required: How many of the agent's threads are in this folder, test and live mail alike.
      - `unread` integer, required: 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.
    - `sent` object, required: The agent's threads in the `sent` folder; both counts are 0 when there are none.
      - `threads` integer, required: How many of the agent's threads are in this folder, test and live mail alike.
      - `unread` integer, required: 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.
  - `labels` object[], required: Every label on the agent's inbox threads, with thread and unread counts.
    - `id` string, nullable, required: Null for a name with no label object behind it.
    - `name` string, required: The label's name: the label object's own spelling when one matches, ignoring case; otherwise as the threads carry it.
    - `color` string, nullable, required: The matching label object's colour, a palette name. Null for a name with no label object behind it.
    - `threads` integer, required: How many of the agent's inbox threads carry this label, test and live mail alike.
    - `unread` integer, required: How many of those threads are unread, counted in the key's own mode like a folder's `unread`.
  - `last_message_at` string, date-time, nullable, required: When a message last joined any of the agent's threads, in any folder, trash included. Null when the agent has no threads.

## Other responses

- `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.

---

[API](https://skmtc.dev/mails/apis/mails-ai-api.md) · [All operations](https://skmtc.dev/mails/apis/mails-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mails/apis/mails-ai-api/revisions/4d4930a8c33b?raw)