---
title: "List agent inboxes"
method: GET
path: "/api/v1/inboxes"
tags: ["Agent inboxes"]
---

# List agent inboxes

`GET /api/v1/inboxes`

## Request

- Base URL: `https://supermailos.com`
- URL: `https://supermailos.com/api/v1/inboxes`
- Auth: HTTP bearer

The agent inboxes this key can see: a person's key, the ones its person can open (plus the workspace's allowance); an agent key, its own.

## Response `200`

Agent inboxes.

- object
  - `inboxes` AgentInbox[], required
    - `id` string, required: Also its mailbox id: pass it as `mailbox` to the mail endpoints.
    - `address` string, email, required
    - `name` string, required: What the agent is called; it signs its mail with it.
    - `description` string
    - `status` 'active' | 'paused', required
    - `paused` object
      - `reason` string
      - `by` 'system' | 'person'
      - `since` string, date-time
      - `until` string, date-time: Absent: until a person resumes it.
    - `sponsor` object, nullable, required: The person who answers for the agent: approvals and alerts go to them.
      - `id` string
      - `name` string
      - `email` string, email
    - `sendMode` 'approval' | 'known' | 'open', required
    - `inboundMode` 'all' | 'verified' | 'allowlist', required
    - `dailySendCap` integer, required
    - `newRecipientsDailyCap` integer, required
    - `allowSenders` string[], required: Addresses or `@domains` the agent may read in `allowlist` mode.
    - `blockSenders` string[], required: Never shown to the agent.
    - `allowRecipients` string[], required: The agent may write to these without approval.
    - `disclosure` boolean, required: Its mail ends with a line saying an AI agent sent it, for whom.
    - `createdVia` 'app' | 'api' | 'mcp'
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time
    - `pendingApprovals` integer: Emails waiting for a person (people's keys only).
  - `allowance` object
    - `used` integer
    - `limit` integer, nullable: `null`: unlimited.

## Other responses

- `401`: Missing, invalid or revoked API key.
- `403`: The key lacks the scope (`missing_scope`) or the access (`forbidden`).
- `404`: Not found — or not reachable with this key.
- `429`: Too many requests.

---

[API](https://skmtc.dev/supermailos/apis/supermailos-api.md) · [All operations](https://skmtc.dev/supermailos/apis/supermailos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/supermailos/apis/supermailos-api/revisions/5bd0ce2ee269?raw)