Skip to main content
GET
List mailboxes

Authorizations

X-API-Key
string
header
required

Query Parameters

search
string | null
Maximum string length: 320
connection_status
enum<string> | null

Whether the mailbox's grant currently authenticates.

Available options:
connected,
disconnected
health
enum<string> | null

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.

Available options:
verified,
connected,
disconnected
provider
enum<string> | null

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.

Available options:
google_workspace,
google_workspace_dwd
sender_profile_id
string<uuid> | null
sent_on
enum<string> | null

Which of a mailbox's days the Mailboxes grid narrows to: its sender's today or yesterday.

Available options:
today,
yesterday
sort
string | null
Pattern: ^(email_address|display_name|provider|connection_status|sender_profile_id)$
order
string
default:asc
Pattern: ^(asc|desc)$
limit
integer
default:50
Required range: 1 <= x <= 200
offset
integer
default:0
Required range: x >= 0

Response

Successful Response

items
MailboxReadSchema · object[]
required
total
integer
required