Connect Mailbox
Start connecting a Gmail/Outlook/IMAP mailbox: returns the provider's hosted-auth URL. When the user finishes, the provider calls ``/mailboxes/connect/callback`` and the mailbox appears in the list. Pass ``mailbox_id`` to reconnect an existing mailbox. The browser is then sent to ``{WEB_BASE_URL}/app/settings/mailboxes`` (or ``/app/onboarding`` with ``return_to: onboarding``) with ``?connected=1`` on success or ``?connected=0`` on failure.
API key access
mailboxes:write scope with an API key (ro_pat_...). A signed-in session uses the caller's role./api/v1/mailboxes/connectAccess token from /api/v1/auth/login, or an API key (ro_pat_..., RO-176) from /api/v1/workspaces/current/api-keys: the key implies its workspace and needs the route's scope. MCP connectors (/api/v1/mcp only) may use an OAuth access token (ro_oat_..., RO-284).
In: header
Header Parameters
Id of the workspace to act on (must be a member).
Reconnect this mailbox (e.g. after needs_reauth).
uuid"settings"Response Body
curl -X POST "http://localhost:8000/api/v1/mailboxes/connect" \ -H "X-Workspace-Id: string" \ -H "Content-Type: application/json" \ -d '{}'{
"url": "string",
"expires_at": "2019-08-24T14:15:22Z"
}{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string",
"input": null,
"ctx": {}
}
]
}