Handle Email Conversations

Feather can run customer email as a conversation channel. You connect a mailbox, inbound mail creates or continues a conversation thread, and your assistant drafts replies that you can review before they go out.

Connect a mailbox

Connect a Gmail or Microsoft mailbox through hosted OAuth. Start the flow bound to an assistant (or team):

curl -X POST https://api-sandbox.featherhq.com/v1/email/accounts/connect \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "<agent_id>", "login_hint": "support@example.com" }'

Response

{ "authorize_url": "https://...", "state": "..." }

Send the user to authorize_url to grant access. Once connected, list your mailboxes:

curl https://api-sandbox.featherhq.com/v1/email/accounts \
  -H "x-api-key: <your_api_key>"

Each account reports its address, provider (gmail or microsoft), and status (pending, active, paused, error, needs_reauth, or retired). Update the signature or re-bind the assistant with PATCH /v1/email/accounts/{account_id}.

Drafts and approval

Assistant replies are created as drafts so a human can review them before they send. A draft is authored against a conversation (session_id) and a connected account_id.

curl -X POST https://api-sandbox.featherhq.com/v1/email/drafts \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "<conversation_id>",
    "account_id": "<account_id>",
    "mode": "human_only",
    "subject": "Re: Order #12345",
    "body_html": "<p>Thanks for reaching out — your order shipped today.</p>",
    "to": [{ "address": "customer@example.com" }]
  }'

In v1, mode must be human_only — a human reviews and approves every draft before it sends. (copilot, which lets the assistant auto-draft, is reserved for a future release and currently returns 422.) Approve and send a draft with:

curl -X POST https://api-sandbox.featherhq.com/v1/email/drafts/<draft_id>/approve \
  -H "x-api-key: <your_api_key>"

A draft moves through draft → submitted → approved → sending → sent (or failed/discarded). You can only edit a draft while it is in draft. List drafts for a conversation with GET /v1/email/drafts?session_id=<id>.

Threads and delivery

GET /v1/email/threads/{thread_id} — the full thread: participants, subject, and every message.
GET /v1/email/messages/{message_id}/events — the delivery audit trail for a sent message (delivery status and events).

Get Started

Core Concepts

Guides

Channels

Handle Email Conversations

Connect a mailbox

Drafts and approval

Threads and delivery

Next steps

Human-in-the-loop

Channels

​Connect a mailbox

​Drafts and approval

​Threads and delivery

​Next steps

Human-in-the-loop

Channels

Connect a mailbox

Drafts and approval

Threads and delivery

Next steps