`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:readaccounting:write

Who can call it

admin, finance, contributor

Retries

No idempotency key

MCP

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

Fields

providerenumRequired
gmailoutlook
loginHintstring (email)
at most 320 characters
returnTostring
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\\]*)?)$
inboxSearchIdstring (ID)
The ID of the related record.
popupboolean
dailyChecksboolean
modeenum
persistenttemporary

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"
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/mailboxes.connect.start", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "provider": "gmail"
  }),
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os

import requests

response = requests.post(
    "https://app.getoatmilk.com/api/v1/accounting/mailboxes.connect.start",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
    },
    json={
        "provider": "gmail",
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

Response

{
  "data": { … }
}

Try it

Checks your input with this action’s real schema and answers like the API, with synthetic data. No key needed, and nothing changes.

Input

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

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"
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/mailboxes.connect.start", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "provider": "gmail"
  }),
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os

import requests

response = requests.post(
    "https://app.getoatmilk.com/api/v1/accounting/mailboxes.connect.start",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
    },
    json={
        "provider": "gmail",
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

Fields

Example

Try it