---
title: "List mailboxes"
method: GET
path: "/mailboxes/"
tags: ["senders"]
---

# List mailboxes

`GET /mailboxes/`

## Request

- Base URL: `https://api.getoneprofile.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getoneprofile.ai/mailboxes/`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

The ops list and the profile editor's picker share this endpoint. Two status filters, and they read differently on purpose: `connection_status` is the stored grant state, where `connected` means anything that is not broken; `health` is the three-way split the Status column draws, where `verified` is a grant that passed its latest check (one runs every hour) and `connected` narrows to one that has not passed a check yet, or whose latest check got a definite error back that was not a refusal.

## Query parameters

- `search` string, nullable
- `connection_status` 'connected' | 'disconnected': Whether the mailbox's grant currently authenticates.
- `health` 'verified' | 'connected' | 'disconnected': The three states the Status column draws, as one filterable value. DERIVED, never stored: it folds ``connection_status`` together with whether ``last_verified_at`` holds a stamp. A mailbox nobody has checked since it connected and one checked this morning are different answers to "is this grant still good?", and the ops screen has to be able to ask for either. Deliberately NOT members of :class:`MailboxConnectionStatus`. That enum is the stored column type and the value on every mailbox response, and eleven places in the domain compare against ``CONNECTED`` by identity. A third member there would put a value on the wire that no row can hold and would silently weaken every one of those checks. Two callers also already send ``connection_status=connected`` meaning "not broken" (the send-a-test picker and the notification settings page), and they must keep that meaning.
- `provider` 'google_workspace' | 'google_workspace_dwd': Which email provider a mailbox connects through. Only Google Workspace ships so far; every provider is implemented behind ``providers.EmailProviderBase`` so Office 365 and IMAP/SMTP can be added later without touching callers. ``GOOGLE_WORKSPACE`` holds a per-mailbox OAuth grant (consent screen, refresh token). ``GOOGLE_WORKSPACE_DWD`` holds no grant at all: tokens are minted on demand via domain-wide delegation as the platform service account, so its rows carry an empty ``refresh_token`` forever. It is the path imported fleets (e.g. InboxKit) connect through.
- `sender_profile_id` string, uuid, nullable
- `sent_on` 'today' | 'yesterday': Which of a mailbox's days the Mailboxes grid narrows to: its sender's today or yesterday.
- `sort` string, nullable: The column to order by. `connection_status` orders by the Status column's three states, disconnected first, then connected, then verified; `sender_profile_id` by the sender's name, with unassigned mailboxes last. Ties go by address. Leave empty for disconnected first, then by address.
- `order` string
- `limit` integer
- `offset` integer

## Response `200`

Successful Response

- MailboxPageSchema
  - `items` MailboxReadSchema[], required
    - `bounce_rate` number, nullable: DSNs / accepted sends, lifetime.
    - `connection_status` 'connected' | 'disconnected', required: Whether the mailbox's grant currently authenticates.
    - `created_at` string, date-time, required
    - `daily_send_limit` integer, required
    - `disconnected_at` string, date-time, nullable, required
    - `disconnected_reason` string, nullable, required
    - `email_address` string, required
    - `id` string, uuid, required
    - `last_verified_at` string, date-time, nullable: When the grant last passed its check.
    - `provider` 'google_workspace' | 'google_workspace_dwd', required: Which email provider a mailbox connects through. Only Google Workspace ships so far; every provider is implemented behind ``providers.EmailProviderBase`` so Office 365 and IMAP/SMTP can be added later without touching callers. ``GOOGLE_WORKSPACE`` holds a per-mailbox OAuth grant (consent screen, refresh token). ``GOOGLE_WORKSPACE_DWD`` holds no grant at all: tokens are minted on demand via domain-wide delegation as the platform service account, so its rows carry an empty ``refresh_token`` forever. It is the path imported fleets (e.g. InboxKit) connect through.
    - `reply_rate` number, nullable: Genuine replies / accepted sends, lifetime.
    - `sender_profile_id` string, uuid, nullable, required
    - `updated_at` string, date-time, required
    - `usage` MailboxUsageReadSchema: Volume only; the ceiling it runs against is the mailbox's `daily_send_limit`.
      - `sent_today` integer, required
      - `sent_yesterday` integer, required
  - `total` integer, required

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `422`: Invalid request made to the API.
- `500`: Internal server error.
- `502`: Bad gateway error.
- `503`: Service unavailable.

---

[API](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile.md) · [All operations](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile/llms.txt) · [OpenAPI document](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile/revisions/4a6bd71e3f02?raw)