# mailboxes.connect.start

Start connecting the signed-in member's own Gmail or Outlook inbox with read-only access. Returns the provider's consent URL; the member finishes in the browser. dailyChecks (default on for Connected inboxes, explicitly off for onboarding and Find in my inbox) decides whether Oatmilk checks the new inbox every day, starting 90 days back; without it the inbox is read only when the member asks, from today. Reconnecting an inbox keeps it paused if it was, and only turns daily checks on, never off. Optional returnTo (a workspace page or /onboarding) brings them back there, popup reports back to the page that opened the window and closes it, and inboxSearchId starts that member's waiting inbox search as soon as the inbox connects. mode temporary (with inboxSearchId, never dailyChecks) asks for read-only access for that one search instead: no offline access, the token is held sealed for at most an hour, bound to that search and member, never checked daily or by anything else, never listed as a connected inbox, and revoked (where the provider allows) and wiped when the search finishes, is stopped or expires. These choices stay on the server behind a single-use nonce, and the exchange uses PKCE. Dashboard only.

`POST /api/v1/accounting/mailboxes.connect.start`

Permissions: `accounting:read`, `accounting:write` · Roles: admin, finance, contributor

Not available over MCP: The inbox owner agrees in the provider's own window.

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `provider` | enum | Yes | One of: `gmail`, `outlook`. |
| `loginHint` | string (email) |  | at most 320 characters. |
| `returnTo` | string |  | at most 500 characters; Matches ^(?:\/onboarding(?:[?#][^\s\\]*)?\|\/(?:accounting\|ops\|inbox\|checklist\|calendar\|ai\|compliance\|chief-of-staff\|logs\|history\|developers\|settings\|finance\|legal\|people\|insights)(?:[/?#][^\s\\]*)?\|\/(?:[?#][^\s\\]*)?)$. |
| `inboxSearchId` | string (ID) |  | The ID of the related record. |
| `popup` | boolean |  |  |
| `dailyChecks` | boolean |  |  |
| `mode` | enum |  | One of: `persistent`, `temporary`. |

## Example request

```bash
curl https://app.getoatmilk.com/api/v1/accounting/mailboxes.connect.start \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "gmail"
}'
```

Reference page: https://app.getoatmilk.com/docs/api/mailboxes.connect.start