---
title: "Begin connecting a mailbox via the hosted-auth flow"
method: POST
path: "/v1/email/accounts/connect"
tags: ["email"]
---

# Begin connecting a mailbox via the hosted-auth flow

`POST /v1/email/accounts/connect`

## Request body

- ConnectMailboxRequest — 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, nullable
  - `agent_revision_id` string, uuid, nullable
  - `team_id` string, uuid, nullable
  - `team_revision_id` string, uuid, nullable
  - `login_hint` string, nullable

## Response `200`

Successful Response

- ConnectMailboxResponse — Returns the URL the frontend should redirect / popup the user to.
  - `authorize_url` string, required
  - `state` string, required

## Other responses

- `400` — Bad request
- `401` — Authentication required
- `422` — Validation Error

---

[API](https://skmtc.net/oneloop-hq/apis/feather-api.md) · [All operations](https://skmtc.net/oneloop-hq/apis/feather-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oneloop-hq/feather-api/revisions/5a5597ebb2d6/schema)