Skip to main content
POST
Connect one mailbox of a connected Microsoft 365 organization

Authorizations

X-API-Key
string
header
required

Body

application/json

One mailbox of a granted Microsoft 365 organization to connect.

email_address
string
required
Required string length: 3 - 320
tenant_id
string
required
Required string length: 1 - 64
daily_send_limit
integer | null
Required range: 1 <= x <= 2000
sender_profile_id
string<uuid> | null

Response

Successful Response

connection_status
enum<string>
required

Whether the mailbox's grant currently authenticates.

Available options:
connected,
disconnected
created_at
string<date-time>
required
daily_send_limit
integer
required

The daily send limit set on the mailbox.

daily_send_limit_cap
enum<string> | null
required

Why today's ceiling is below 2,000: personal_gmail, or new_mailbox for a mailbox in its first 30 days. Null when it is not.

Available options:
personal_gmail,
new_mailbox,
onmicrosoft_domain
daily_send_limit_ceiling
integer
required

The most the mailbox may send today, whatever its limit says: 500 for personal Gmail and for a mailbox in its first 30 days after it was first connected, 2,000 otherwise.

daily_send_limit_max
integer
required

The most daily_send_limit may be set to: 500 for a personal Gmail address, 2,000 for any other mailbox.

disconnected_at
string<date-time> | null
required
disconnected_reason
string | null
required
effective_daily_send_limit
integer
required

What the mailbox may send today: its limit, held under today's ceiling. Usage and capacity count against this.

email_address
string
required
id
string<uuid>
required
provider
enum<string>
required

Which email provider a mailbox connects through.

Every provider is implemented behind providers.EmailProviderBase, so callers never see which one a mailbox uses.

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. GOOGLE_CLERK is the Google sign-in itself: the onboarding wizard's person consents to Gmail once, at sign-up, and Clerk keeps that grant, so the row's refresh_token holds the Clerk user id whose Google connection each fresh token is read from.

MICROSOFT_CLERK is the Microsoft 365 twin of GOOGLE_CLERK: Outlook through Microsoft Graph, with the grant held by the person's Clerk Microsoft sign-in. The row's refresh_token holds the Clerk user id and provider_account_id the Clerk external account the token is read from. MICROSOFT_365_APP is the twin of GOOGLE_WORKSPACE_DWD: Graph with an application token for a tenant whose admin granted Oneprofile once, so its rows carry an empty refresh_token too.

Available options:
google_workspace,
google_workspace_dwd,
google_clerk,
microsoft_clerk,
microsoft_365_app
sender_profile_id
string<uuid> | null
required
updated_at
string<date-time>
required
bounce_rate
number | null

DSNs / accepted sends, lifetime.

last_verified_at
string<date-time> | null

When the grant last passed its check.

reply_rate
number | null

Genuine replies / accepted sends, lifetime.

usage
MailboxUsageReadSchema · object | null

Volume only; the ceiling it runs against is the mailbox's effective_daily_send_limit.