Quickstart

This connects one account — your own — and sends a message through it. No frameworks, no SDK, just curl. Everything here works on the free plan.

1. Get a keyCopy Anchor Link

Create a project in the dashboard and copy a sandbox key from API keys. Keys are scoped to one environment, so a sandbox key cannot touch production data by accident.

export AUX0_API_KEY="aux0_test_..."

2. Create a hosted auth linkCopy Anchor Link

aux0 serves the page your user links their account on, so no credential reaches your product. end_user_id is your own identifier for that person.

curl https://api.aux0.com/v1/hosted_auth \
  -H "Authorization: Bearer $AUX0_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": "u_your_own_id",
    "providers": ["gmail", "outlook", "imap"],
    "expires_in": 3600
  }'

{
  "id": "hal_2kd9fQmLp3",
  "url": "https://auth.aux0.com/r/2kd9fQmLp3",
  "expires_at": "2026-10-22T15:20:00Z"
}

3. Open the link and connectCopy Anchor Link

Open that URL yourself and link an account. Gmail and Outlook hand you to their own consent screen; iCloud and IMAP ask for a server and an app password.

When you finish, aux0 posts account.connected to your webhook if you have one. You can also poll:

curl "https://api.aux0.com/v1/accounts?end_user_id=u_your_own_id" \
  -H "Authorization: Bearer $AUX0_API_KEY"

{
  "items": [
    {
      "id": "acc_8kd2nR4p",
      "provider": "gmail",
      "handle": "Your Name",
      "status": "syncing",
      "connected_at": "2026-10-22T14:21:08Z"
    }
  ],
  "total": 1
}

syncing means the history backfill is running. Reads work during a backfill and sends are queued, so there is nothing to wait for.

4. Read the conversationsCopy Anchor Link

curl "https://api.aux0.com/v1/chats?account_id=acc_8kd2nR4p&limit=5" \
  -H "Authorization: Bearer $AUX0_API_KEY"

The same request works whichever provider the account is — that is the point of the thing.

5. Send a messageCopy Anchor Link

curl https://api.aux0.com/v1/chats/cht_8Lp3nBxQ/messages \
  -H "Authorization: Bearer $AUX0_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Sent through aux0." }'

{
  "id": "msg_2tKd9fQm",
  "status": "sent",
  "sent_at": "2026-10-22T14:33:51Z"
}

A status of queued rather than sent means the account is inside its pacing window and aux0 is holding the message rather than letting the provider reject it. It goes out on its own; you do not retry.

6. Receive repliesCopy Anchor Link

Polling works, but the replies arrive within seconds over a webhook.

curl https://api.aux0.com/v1/webhooks \
  -H "Authorization: Bearer $AUX0_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/hooks/aux0",
    "events": ["message.received", "account.needs_attention"]
  }'

Verify the signature before you trust a request — see Webhooks.

What nextCopy Anchor Link

• Account health is the page to read before you go to production. Sessions break, and how your product handles that is most of the difference between an integration users trust and one they do not.
• Hosted auth covers branding the page and reconnecting a broken account.
• Environments covers sandbox and production.