Connected accounts
The object everything else hangs off, and the one aux0 bills on.
A connected account is one mailbox, calendar or address book a user has linked. Every thread, message, event and contact belongs to exactly one.
The shape
{
"id": "acc_8kd2nR4p",
"provider": "gmail",
"handle": "Maya Rao",
"provider_id": "ACoAAB2xQm4Bmaya",
"end_user_id": "u_maya",
"status": "connected",
"auth": "oauth",
"connected_at": "2026-06-18T09:14:00Z",
"last_sync_at": "2026-10-22T14:19:20Z",
"budget": {
"windows": [
{ "label": "Sends", "used": 412, "limit": 2000, "resets_at": "..." },
{ "label": "Recipients", "used": 1180, "limit": 10000, "resets_at": "..." }
]
}
}Status
| Status | What it means | What still works |
|---|---|---|
connected | Reachable and inside its budget. | Everything. |
syncing | The first backfill is running. | Reads work. Sends are accepted and queued. |
needs_attention | The provider wants the end user. | Reads work on cached history. Sends are queued. |
paused | Paused by you. | Nothing is sent or polled. |
disconnected | The provider refused the session and aux0 stopped retrying. | Cached history only. |
needs_attention and disconnected both carry an attention object with a
machine-readable code and a sentence written for your end user. See
Account health.
The end user
end_user_id is your identifier, passed when you create the hosted auth
link. aux0 stores that string and nothing else about the person unless you
choose to send a name or an email for display. Two accounts with the same
end_user_id are two channels for one person, which is how a product offers
"connect your mail and your calendar" as one step.
Rate budgets
Each provider enforces its own windows — Gmail's daily send and recipient quotas, Graph's per-mailbox throttling, an IMAP server's connection limit. Aux0 tracks what each account has spent and paces sends to stay inside them.
This is the behaviour worth understanding before you build a scheduler on top:
- A send that would exceed a window is queued, not rejected. It goes out when the window has room.
budget.windowstells you what is left, so your own scheduler can plan rather than discover.- A new account is warmed over its first days rather than run at full rate.
The alternative is letting the provider reject the send, which costs the account some trust each time. Pacing is slower and much safer.
Activity window
Each account carries a weekly window — the days and the hours it is allowed to act — stored with its own timezone, so it follows wall clock through a daylight-saving change rather than drifting an hour twice a year.
- Work scheduled outside the window is queued until the window opens. It is not rejected and not run early.
- Nothing from that account touches the provider while the window is closed.
- The default is permissive; narrow it per account when the account's owner keeps regular hours and you want the traffic to look like it.
An account that acts at three in the morning looks like a user who never sleeps, which is one of the strongest automation signals there is. The window is the cheapest thing you can do about it.
Sync state
Each account holds its own sync cursor across reconnects. IMAP can invalidate
a cursor without warning through UIDVALIDITY, and the naive answer is to
re-download the mailbox; Aux0 detects the invalidation and reconciles against
what it already holds.
Deleting one
curl -X DELETE https://api.aux0.com/v1/accounts/acc_8kd2nR4p \
-H "Authorization: Bearer $AUX0_API_KEY"Credentials are destroyed immediately and content within 30 days. The account stops counting towards your bill from the moment it is deleted.