Skip to main content
GET
List mailboxes

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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
provider
enum<string> | null

Which email provider a mailbox connects through.

Phase 1 ships Google Workspace only; 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 — the path imported fleets (e.g. InboxKit) connect through.

Available options:
google_workspace,
google_workspace_dwd
sender_profile_id
string<uuid> | null
sent_on
string | null
Pattern: ^(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