Skip to main content
POST
/
v1
/
email
/
accounts
/
connect
Begin connecting a mailbox via the hosted-auth flow
curl --request POST \
  --url https://api-sandbox.featherhq.com/v1/email/accounts/connect \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "team_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "team_revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "login_hint": "<string>"
}
'
{
  "authorize_url": "<string>",
  "state": "<string>"
}

Authorizations

​
x-api-key
string
header
required

Body

application/json

Initiate a mailbox-connect flow.

agent_id / team_id are captured in the OAuth state so the callback can bind the grant atomically. Both optional — callers can bind later via the binding endpoint — but at most one may be set on a single request (a mailbox binds to either a single agent or a team).

Revision pins (agent_revision_id / team_revision_id) are OPTIONAL: omitting one pins the target's current active revision at bind (pin-at-bind), a non-null value pins that exact revision. Each may only be set alongside its own agent/team id.

​
agent_id
string<uuid> | null
​
agent_revision_id
string<uuid> | null
​
team_id
string<uuid> | null
​
team_revision_id
string<uuid> | null
​
login_hint
string | null
Maximum string length: 320

Response

Successful Response

Returns the URL the frontend should redirect / popup the user to.

​
authorize_url
string
required
​
state
string
required