# Endpoint scope map
> Every AY Inbox API endpoint with the auth types it accepts and the permission it requires, so you know exactly what an API key or OAuth token can reach.
Source: https://docs.ayinbox.com/api/endpoints/
This page is the source of truth for what an API key can and cannot reach. Every route in the backend falls into one of three buckets:
* **API key accepted**: works with both a JWT (dashboard user) and an API key with the listed permission.
* **JWT only**: never reachable via an API key. Used for billing, governance, websocket bootstrap, danger-zone destruction, the OAuth onboarding flow, and admin tools.
* **Public**: no auth required (webhooks with signature verification, health check, OAuth bouncer pages).
When an endpoint says "JWT permission: X / API permission: Y", the dual-auth middleware checks the relevant one based on which credential the caller used.
A member restricted to [selected resources](/guides/team-roles/#access-scope) is held to a short list of read routes whatever credential they use, and those routes filter to their grants: `GET /campaigns`, `/campaigns-overview`, `/campaigns/:id` with its `/logs`, `/steps` and `/ab-variants`, `GET /analytics/dashboard` (whose `campaign_ids` and `folder_ids` filters must name granted campaigns and folders), `/analytics/campaigns/compare`, `/analytics/campaigns/:id` with `/daily` and `/hourly`, `GET /analytics/accounts` and `/analytics/accounts/:id`, `GET /emails` and `/emails/:id`, and the unibox reads `GET /unibox`, `/unibox/count`, `/unibox/overview`, `/unibox/thread`, `/unibox/thread/labels`, `/unibox/scheduled` and `/unibox/:id` (which, for them, does not mark the message read). Their own account routes under `/auth/*`, `/me/*`, `GET /organization`, `/organization/current`, `/organization/switch/:id`, `/invitations`, `GET /subscription`, `/subscription/features`, `GET /timezones` and `POST /getaway` keep working. Every other route answers `403` `member_access_restricted`, and a campaign or mailbox outside their grants answers `404`. An API key's own mailbox allowlist still applies on top: the key reaches the mailboxes on both lists.
All paths below are relative to the versioned base URL `https://api.ayinbox.com/v1` (for example `/campaigns` is `https://api.ayinbox.com/v1/campaigns`). See [versioning](/api/) for details.
Restricted response data and workspace policies [#restricted-response-data-and-workspace-policies]
* `GET /organization/current` returns a restricted summary: `total_campaigns` and `active_campaigns` count granted campaigns; `total_contacts` counts distinct contacts in those campaigns; `email_accounts` counts granted mailboxes; and `emails_sent_today` counts confirmed campaign sends in both granted campaigns and granted mailboxes. `member_count`, `product_description`, `icp_notes` and `voice_profile` are omitted. Unrestricted responses keep their workspace-wide shape.
* `GET /analytics/dashboard` intersects campaign and folder filters with grants before returning `scope.campaign_count`.
* `GET /campaigns/:id/logs` keeps pagination and campaign activity, but restricted responses use safe messages and explicitly selected metadata. Mailbox addresses, caps, cross-campaign sending state, warmup health and account IDs outside mailbox grants are removed. Tracking domains, raw provider errors, unknown fields and nested metadata are not exposed. Granting a campaign alone does not grant its senders.
* `GET /auth/me` and `/unibox/overview` include only categories applied to messages in accessible mailboxes for restricted members. Unrestricted members keep the workspace category registry. Inbox access is mailbox-based: granting a shared mailbox exposes its conversations from other campaigns too.
* `GET /unibox/overview` includes `drafts`, the distinct conversation count across mailbox drafts and visible pending inbox-agent replies, scoped to accessible mailboxes. Older servers omit this field; during rolling upgrades the dashboard uses their mailbox-only Drafts count until it is available.
* `GET /unibox/thread/labels` checks for a message in the selected organization and effective mailbox allowlist before listing labels. Unknown, cross-workspace and inaccessible threads have the same `404`. An accessible thread with no labels returns an empty list.
* `GET /emails` resolves a pagination cursor only inside the selected organization and effective mailbox allowlist. A cursor outside either boundary does not supply a timestamp for pagination.
Workspace creation and limit-request routes are exceptions to the route-wide refusal described above: they authorize the account or target workspace in the service. `POST /organization` refuses accounts whose memberships are all restricted with `403` `member_access_restricted`, unless they are instance administrators. Accounts with no memberships or at least one unrestricted membership remain subject to the existing creation limits. Submitting or listing `/organization/:orgId/limit-requests`, and deleting `/limit-requests/:id`, requires an unrestricted membership in the request's target organization. Switching the selected workspace does not bypass these checks.
Workspace notifications and owner-addressed realtime delivery also check current organization membership. Resource ownership alone does not authorize a workspace-wide event. Restricted, removed and unaccepted members are excluded from workspace notifications, including persisted feeds and deferred email/push delivery. Personal sign-in security notices remain available. See [realtime authorization and revocation](/api/realtime/#channels) for the 30-second refresh bound on open resource channels.
These checks use existing grants on hosted and self-hosted instances and need no new migration or configuration. Existing unrestricted behavior is preserved.
API key accepted [#api-key-accepted]
Emails [#emails]
`PATCH /emails/:id` validates `warmup_start_time` and `warmup_end_time` together: the end must be later than the start on the same day. A partial time patch uses the other stored endpoint; an invalid pair returns `400`. Unrelated patches do not rewrite existing invalid hours. See [warmup hours](/guides/warmup/).
| Method | Path | API Permission |
| ------ | ------------------------------ | ---------------- |
| GET | `/emails` | `READ_EMAILS` |
| GET | `/emails/:id` | `READ_EMAILS` |
| PATCH | `/emails/:id` | `WRITE_EMAILS` |
| PATCH | `/emails/tags` | `WRITE_EMAILS` |
| GET | `/emails/allowance` | `READ_EMAILS` |
| GET | `/emails/:id/track` | `READ_EMAILS` |
| PATCH | `/emails/:id/track` | `WRITE_EMAILS` |
| POST | `/emails/:id/track/verify` | `WRITE_EMAILS` |
| PATCH | `/emails/:id/direct-tracking` | `WRITE_EMAILS` |
| GET | `/emails/:id/sync` | `READ_EMAILS` |
| PUT | `/emails/:id/sync` | `WRITE_EMAILS` |
| GET | `/emails/:id/certificates` | `READ_EMAILS` |
| GET | `/emails/:id/identity` | `READ_EMAILS` |
| POST | `/emails/:id/identity/refresh` | `WRITE_EMAILS` |
| GET | `/emails/:id/auth-check` | `READ_EMAILS` |
| POST | `/emails/:id/auth-check` | `WRITE_EMAILS` |
| GET | `/emails/:id/behavior` | `READ_EMAILS` |
| PUT | `/emails/:id/behavior` | `WRITE_EMAILS` |
| GET | `/emails/:id/behavior/plan` | `READ_EMAILS` |
| POST | `/emails/:id/hold` | `WRITE_EMAILS` |
| POST | `/emails/:id/release` | `WRITE_EMAILS` |
| DELETE | `/emails/:id` | `WRITE_EMAILS` |
| POST | `/emails/:id/send` | `SEND_CAMPAIGNS` |
Campaigns and sequences [#campaigns-and-sequences]
Campaigns, steps and activity logs are scoped to the selected organization for session callers and the key's organization for API-key callers. Access depends on the permissions below, regardless of who created the campaign. Step updates and deletes also require the step to belong to the campaign in the URL. Campaign analytics, including daily, hourly and comparison endpoints, use this same organization boundary and require `READ_ANALYTICS` (or **View analytics** for session callers).
| Method | Path | API Permission |
| --------------------- | ------------------------------------------------ | ----------------------------------------------------- |
| GET | `/campaigns` | `READ_CAMPAIGNS` |
| GET | `/campaigns-overview` | `READ_CAMPAIGNS` |
| POST | `/campaigns-estimate` | `READ_CAMPAIGNS` |
| POST | `/campaigns` | `WRITE_CAMPAIGNS` |
| GET | `/campaigns/:id` | `READ_CAMPAIGNS` |
| PATCH | `/campaigns/:id` | `WRITE_CAMPAIGNS` |
| DELETE | `/campaigns/:id` | `WRITE_CAMPAIGNS` |
| POST | `/campaigns/:id/duplicate` | `WRITE_CAMPAIGNS` |
| GET | `/campaigns/:id/attachments` | `READ_CAMPAIGNS` |
| POST | `/campaigns/:id/attachments` | `WRITE_CAMPAIGNS` |
| DELETE | `/campaigns/:id/attachments/:attachmentId` | `WRITE_CAMPAIGNS` |
| GET | `/campaigns/:id/segments` | `READ_CAMPAIGNS` |
| PUT | `/campaigns/:id/segments` | `WRITE_CAMPAIGNS` |
| GET | `/campaigns/:id/advanced` | `READ_CAMPAIGNS` |
| PATCH | `/campaigns/:id/advanced` | `WRITE_CAMPAIGNS` |
| GET | `/campaigns/:id/ab-variants` | `READ_CAMPAIGNS` |
| POST | `/campaigns/:id/ab-variants` | `WRITE_CAMPAIGNS` |
| PATCH | `/campaigns/:id/ab-variants/:variantId` | `WRITE_CAMPAIGNS` |
| DELETE | `/campaigns/:id/ab-variants/:variantId` | `WRITE_CAMPAIGNS` |
| GET | `/campaigns/:id/ab-analysis` | `READ_ANALYTICS` |
| POST | `/campaigns/:id/preflight` | `SEND_CAMPAIGNS` |
| POST | `/campaigns/:id/test-email` | `SEND_CAMPAIGNS` |
| POST | `/campaigns/:id/start` | `SEND_CAMPAIGNS` |
| POST | `/campaigns/:id/stop` | `SEND_CAMPAIGNS` |
| GET | `/campaigns/:id/placement-monitor` | `READ_CAMPAIGNS` |
| PUT | `/campaigns/:id/placement-monitor` | `SEND_CAMPAIGNS` |
| DELETE | `/campaigns/:id/placement-monitor` | `SEND_CAMPAIGNS` |
| GET | `/campaigns/:id/leads/:contactId/hold` | `READ_CAMPAIGNS` |
| POST | `/campaigns/:id/leads/:contactId/pause` | `WRITE_CAMPAIGNS` |
| POST | `/campaigns/:id/leads/:contactId/resume` | `WRITE_CAMPAIGNS` |
| GET | `/campaigns/:id/reviews` | `READ_CAMPAIGNS` + `READ_CONTACTS` |
| POST | `/campaigns/:id/reviews/:reviewId/approve` | `SEND_CAMPAIGNS` + `READ_CONTACTS` |
| POST | `/campaigns/:id/reviews/:reviewId/edit` | `SEND_CAMPAIGNS` + `READ_CONTACTS` |
| POST | `/campaigns/:id/reviews/:reviewId/reject` | `SEND_CAMPAIGNS` + `READ_CONTACTS` |
| POST | `/campaigns/:id/reviews/bulk-approve` | `SEND_CAMPAIGNS` + `READ_CONTACTS` |
| GET | `/campaigns/:id/leads/:contactId/cc` | `READ_CAMPAIGNS` + `READ_CONTACTS` |
| PUT | `/campaigns/:id/leads/:contactId/cc` | `WRITE_CAMPAIGNS` + `READ_CONTACTS` |
| GET | `/campaigns/:id/leads/:contactId/cc/suggestions` | `READ_CAMPAIGNS` + `READ_CONTACTS` |
| GET | `/campaigns/:id/logs` | `READ_CAMPAIGNS` |
| GET | `/campaigns/:id/send-plan` | `READ_CAMPAIGNS` |
| GET | `/campaigns/:id/forms` | `READ_CAMPAIGNS` |
| GET/POST/PATCH/DELETE | `/campaigns/:id/steps[/:sid]` | `READ_CAMPAIGNS` for GET, `WRITE_CAMPAIGNS` otherwise |
| PATCH | `/campaigns/:id/step-layout` | `WRITE_CAMPAIGNS` |
| POST | `/generation/write` | `WRITE_CAMPAIGNS` |
| POST | `/generation/edit` | `WRITE_CAMPAIGNS` |
| POST | `/generation/ai-variable` | `WRITE_CAMPAIGNS` |
| GET | `/email-images` | `READ_CAMPAIGNS` |
| POST | `/email-images` | `WRITE_CAMPAIGNS` |
| DELETE | `/email-images/:id` | `WRITE_CAMPAIGNS` |
The `hold`, `pause` and `resume` calls under `/campaigns/:id/leads/:contactId/` hold one contact's flow inside one campaign: an out-of-office auto-reply writes one automatically, and a member can write one by hand. The contact stays subscribed and stays a lead, so this is not an unsubscribe and not a suppression. Both writes state an absolute hold rather than applying a delta, and replacing a live hold keeps its original start, so a retry lands on the same row and neither needs an `Idempotency-Key`. See [pause a lead](/api/reference/campaigns/#pause-a-lead).
The `reviews` calls are the [first-email review queue](/guides/campaigns/#review-first-emails-before-they-send) of a campaign with `review_first_emails` on. `GET` lists the queue oldest render first, `?status=` `pending` (the default), `approved` or `rejected`, `?limit=` 1 to 100, `?cursor=` the opaque `pagination.next_cursor`, and returns `data`, `pagination` and `counts` by status. Each item carries the rendered `subject`, `body_html` and `body_plain`, the mailbox it was rendered for, its `version` and a `text_hash`. Each item shows a recipient's address, name and personalized text, so every call also takes `READ_CONTACTS` (for a member, **View contacts**). Approving lets mail go out, so every write takes `SEND_CAMPAIGNS` (for a member, **Send campaigns**):
* `approve` takes `{"text_hash": "..."}`, the hash of the text the caller reviewed, and refuses with `409 review_text_changed` when the stored text no longer matches it.
* `edit` takes the same `text_hash` plus `subject` and `body_plain` (and optionally `body_html`; without it an existing HTML part is rebuilt from the text), stores them as a new version and approves it.
* `reject` takes an optional `{"reason": "..."}` (up to 500 characters) and skips the lead.
* `bulk-approve` takes `{"items": [{"id": "...", "text_hash": "..."}]}`, up to 200, approves every item whose text still matches, and answers `{"approved": [...], "refused": [{"id", "code", "reason"}]}`. If a write fails partway, the items already approved stay approved and the rest come back refused with `internal_error`, so retry only those; a failure before anything was approved is a `500`.
Each write changes a pending item once and answers `409 review_not_pending` after that, and each accepts an `Idempotency-Key`, so a retried request is either replayed or refused rather than applied twice.
Turning review on through `PATCH /campaigns/:id` takes `WRITE_CAMPAIGNS` like any other setting. Turning it off on a campaign that has it on releases every waiting first email, so that also takes `SEND_CAMPAIGNS` (for a member, **Send campaigns**) and answers `403 review_off_needs_send` without it.
The `cc` calls under the same path set the contacts copied on every email to one lead. Their answers carry contact names and addresses, so they need contact read access as well as the campaign scope. `PUT` sends the whole list, so a retry lands on the same state and needs no `Idempotency-Key`. See [set a lead's CC](/api/reference/campaigns/#set-a-leads-cc).
`GET /campaigns/:id/forms` reports the forms this campaign links to and what its recipients did with them: personalized links handed out, who opened one, who started filling it in and who submitted. See the [forms guide](/guides/forms/).
`GET /campaigns/:id/send-plan` returns today's sending plan: what the campaign is expected to send, and every limit that decided the number. For an active campaign the plan is computed in the background and served from a stored snapshot, so the read stays fast on a campaign of any size. `computed_at` is when that snapshot was walked, and `stale` is `true` when the campaign has since been edited, started, stopped, or has crossed into a new budget day and a refreshed plan is already being computed: the figures are the last good ones and a current plan follows within moments. A campaign that has no snapshot yet (a brand-new one) is computed on the request instead. See the [send plan guide](/guides/campaigns/#todays-sending-plan).
`/email-images` is the workspace's image library for email bodies. `POST` takes a multipart `file` field (PNG, JPG, GIF or WebP, up to 5 MB) and returns the row with the public `url` you put in an ``; those bytes count against the same storage quota as campaign attachments. `GET` is keyset-paginated newest first (`?limit=` 1 to 100, `?cursor=` the opaque `pagination.next_cursor`). `DELETE` removes the object before the row and refuses with a `503` if storage will not take the delete, so a failed call changes nothing and can be retried; once it succeeds, an image in mail already sent stops loading.
Contacts [#contacts]
| Method | Path | API Permission |
| ------ | ---------------------------------- | ----------------------------------------------------- |
| POST | `/contacts/search` | `READ_CONTACTS` |
| GET | `/contacts/custom-fields` | `READ_CONTACTS` |
| GET | `/contacts/lookup` | `READ_CONTACTS` (plus `READ_UNIBOX` with `thread_id`) |
| POST | `/contacts` | `WRITE_CONTACTS` |
| DELETE | `/contacts` | `BULK_CONTACTS` |
| PATCH | `/contacts` | `BULK_CONTACTS` |
| GET | `/contacts/verification` | `READ_CONTACTS` |
| POST | `/contacts/verification` | `BULK_CONTACTS` |
| GET | `/contacts/:id` | `READ_CONTACTS` |
| PATCH | `/contacts/:id` | `WRITE_CONTACTS` |
| DELETE | `/contacts/:id` | `WRITE_CONTACTS` |
| GET | `/contacts/:id/emails` | `READ_CONTACTS` |
| GET | `/contacts/:id/timeline` | `READ_CONTACTS` |
| GET | `/contacts/:id/campaigns` | `READ_CONTACTS` |
| PUT | `/contacts/:id/consent` | `WRITE_CONTACTS` |
| GET | `/contacts/:id/segments` | `READ_CONTACTS` |
| GET | `/contacts/:id/lead-score` | `READ_CONTACTS` |
| GET | `/contacts/:id/graph` | `READ_CONTACTS` |
| POST | `/contacts/export` | `READ_CONTACTS` |
| POST | `/contacts/import/preview` | `WRITE_CONTACTS` |
| POST | `/contacts/import/commit` | `BULK_CONTACTS` |
| POST | `/contacts/imports` | `WRITE_CONTACTS` |
| GET | `/contacts/imports` | `READ_CONTACTS` |
| GET | `/contacts/imports/:id` | `READ_CONTACTS` |
| PATCH | `/contacts/imports/:id` | `WRITE_CONTACTS` |
| POST | `/contacts/imports/:id/analyze` | `WRITE_CONTACTS` |
| POST | `/contacts/imports/:id/start` | `BULK_CONTACTS` |
| POST | `/contacts/imports/:id/cancel` | `BULK_CONTACTS` |
| GET | `/contacts/imports/:id/failed.csv` | `READ_CONTACTS` |
| GET | `/contacts/:id/notes` | `READ_CONTACTS` |
| POST | `/contacts/:id/notes` | `WRITE_CONTACTS` |
| PATCH | `/contacts/:id/notes/:noteId` | `WRITE_CONTACTS` |
| DELETE | `/contacts/:id/notes/:noteId` | `WRITE_CONTACTS` |
| GET | `/contacts/:id/activities` | `READ_CONTACTS` |
| GET | `/contacts/:id/deals` | `READ_CRM` |
| POST | `/contacts/:id/research` | `AI_RESEARCH` |
| GET | `/contacts/:id/research` | `AI_RESEARCH` |
| POST | `/contacts/research/batch` | `AI_RESEARCH` |
| GET | `/contacts/first-lines[/:jobId]` | `AI_RESEARCH` |
| POST | `/contacts/first-lines` | `AI_RESEARCH` and `BULK_CONTACTS` |
`PUT /contacts/:id/consent` records the contact's [prior consent](/guides/contacts-crm/#prior-consent): `{"given": true}` records it now, with an optional `given_at` (not in the future) and `source` (up to 100 characters, `api` by default for a key and `manual` for a member); `{"given": false}` clears it. It answers `consent_given_at` and `consent_source`. The body states the whole record, so a retry lands on the same state and needs no `Idempotency-Key`. `GET /contacts/:id` reports `consent_given_at`, `consent_source`, `consent_country` (the code the contact's country field names) and `consent_required` (whether the workspace's list holds it).
`GET /contacts/custom-fields` lists the distinct custom-field keys used across your contacts (frequency-ranked), for building personalization pickers and import column mappers. It returns a flat string array under `data`, capped at 200 keys.
The import pair is two steps over the same file: preview parses it and suggests a column mapping (matching headers to your existing custom fields), commit applies the mapping you chose. Commit takes the stricter `BULK_CONTACTS` scope because one call writes up to 50,000 rows. A mapping problem, an unusable custom-field name or no `email` column, is a `400` on the whole request; see [contacts](/api/reference/contacts/).
AI contact research charges credits (2 per run, billable even when it finds nothing) and only saves cited findings. See the [AI contact research](/guides/ai-contact-research/) guide. The batch endpoint accepts up to 500 contact ids and drains in the background. A run's `result.first_line` holds `text`, `fact`, `fact_date` and `source_url`; a `text` of exactly `NO_FACT` means send with no personalization, and runs saved before first lines existed have no `first_line`. A finished run also writes the line onto the contact as the custom fields `first_line`, `first_line_source` and `first_line_checked_at`, unless the contact already holds a first line with no `first_line_source`, which stays as it is.
`POST /contacts/first-lines` starts a [first-line job](/guides/ai-contact-research/#write-first-lines-in-bulk) over up to 5,000 contacts, named with the same [selection](/api/reference/contacts/#selecting-contacts-for-a-bulk-action) as the other bulk actions or as a `segment_id`, with a budget in `max_cost_usd` ($0.05 to $100, default $5). It spends the instance's Looot balance and the workspace's AI credits and writes many contacts, so it needs `BULK_CONTACTS` as well as `AI_RESEARCH` (for a member, `manage_contacts` and `use_ai`). Send an `Idempotency-Key`: a repeated key returns the job the first request started, with `202` and the same body. The answer carries the `job`, `estimated_max_usd` (every contact alone at its company), `budget_usd`, `llm_estimate_usd_per_contact` and `llm_priced`, which is `false` when the model's token prices are unknown and the conservative cap applies. `GET /contacts/first-lines` lists the workspace's latest jobs under `data` (newest first, `limit` 1 to 100, default 20, with no `pagination` or cursor because it is a progress view of recent jobs, not an archive to page through), and `GET /contacts/first-lines/:jobId` returns one with its progress: `contacts_done` of `total`, `written`, `no_fact`, `skipped_fresh`, `kept` (contacts that already held a first line of their own), `skipped`, `failed`, the Looot spend (`looot_spent_micros`, `looot_held_micros` for lookups whose cost Looot did not report), `llm_spent_micros`, `credits_charged` and `budget_reached`. Amounts are in millionths of a dollar.
Segments [#segments]
| Method | Path | API Permission |
| ------ | ------------------------------- | ----------------- |
| GET | `/segments` | `READ_CONTACTS` |
| GET | `/segments/fields` | `READ_CONTACTS` |
| POST | `/segments/preview` | `READ_CONTACTS` |
| POST | `/segments` | `WRITE_CONTACTS` |
| GET | `/segments/:id` | `READ_CONTACTS` |
| PATCH | `/segments/:id` | `WRITE_CONTACTS` |
| DELETE | `/segments/:id` | `WRITE_CONTACTS` |
| POST | `/segments/:id/members` | `WRITE_CONTACTS` |
| POST | `/segments/:id/members/lookup` | `READ_CONTACTS` |
| GET | `/segments/:id/overrides` | `READ_CONTACTS` |
| POST | `/segments/:id/add-to-campaign` | `WRITE_CAMPAIGNS` |
Segments are saved contact audiences: a condition list plus per-contact manual overrides, evaluated live. Contact scopes cover them because a segment is a view over contacts; enrolling one into a campaign writes leads, so that call takes the campaign write scope, as does managing a campaign's linked segments (`/campaigns/:id/segments` above). `POST /contacts/search` and `POST /contacts/export` accept `segment_ids` to scope any contact query to a segment. See [contacts](/api/reference/contacts/#segments) for the condition format.
Lead scoring [#lead-scoring]
| Method | Path | API Permission |
| ------ | ---------------------------------------- | ---------------------------------- |
| GET | `/lead-scoring/profile` | `READ_CONTACTS` |
| PUT | `/lead-scoring/profile` | `BULK_CONTACTS` |
| GET | `/lead-scoring/summary` | `READ_CONTACTS` |
| GET | `/lead-scoring/enrichment-runs[/:runId]` | `READ_CONTACTS` |
| POST | `/lead-scoring/enrichment-runs` | `INTEGRATIONS` and `BULK_CONTACTS` |
[Lead scoring](/guides/lead-scoring/) grades every contact A to D against the workspace's ideal customer profile. `GET /lead-scoring/profile` returns the saved profile, or the default one with `configured: false` before the workspace saves its own. `PUT` replaces it with `enabled` and `criteria` (both required) and takes the bulk contact scope because a change re-grades every contact in the background (for a member, `manage_contacts`); saving the same profile again changes nothing, so a retry is safe without an `Idempotency-Key`. `GET /lead-scoring/summary` counts the scored contacts per grade and how many are up to date with the current profile. `GET /contacts/:id/lead-score` returns one contact's grade, score, hard-rule cap and the reason for each criterion under `lead_score`, which is `null` until the contact is scored; contact search rows carry `lead_score` (`grade` and `score`) when there is one.
Starting a company enrichment run spends the instance's Looot balance and writes company facts that move grades, so it takes `INTEGRATIONS` as well as `BULK_CONTACTS` (for a member, `use_integrations` and `manage_contacts`) and, on a hosted workspace, a paid plan that includes integrations. Send `max_cost_usd` (from $0.05 to $50, $5 by default) and `include_technographics`, and an `Idempotency-Key` header so a retry returns the same run. The answer is `202` with the `run`, `budget_usd` and `worst_case_usd_per_company`.
Company signals [#company-signals]
| Method | Path | API Permission |
| ------------ | ------------------------------- | ----------------------------------- |
| GET | `/signals` | `READ_CONTACTS` |
| GET | `/signals/domains` | `READ_CONTACTS` |
| GET | `/signals/companies` | `READ_CONTACTS` |
| POST | `/signals/companies` | `WRITE_CONTACTS` |
| PATCH/DELETE | `/signals/companies/:companyId` | `WRITE_CONTACTS` |
| GET | `/signals/settings` | `READ_CONTACTS` |
| PUT | `/signals/settings` | `INTEGRATIONS` |
| POST | `/signals/check` | `INTEGRATIONS` and `WRITE_CONTACTS` |
[Company signals](/guides/signals/) are contact data, so reading them takes `READ_CONTACTS` (for a member, `view_contacts`) and editing the watch list takes `WRITE_CONTACTS` (`manage_contacts`). A check and the daily budget spend the instance's Looot balance: `POST /signals/check` also takes `INTEGRATIONS` (`use_integrations` and `manage_contacts` for a member), and `PUT /signals/settings` takes `INTEGRATIONS` and, for a member, `manage_settings`. Both need a paid plan that includes integrations on a hosted workspace. Every route answers `503` `signals_disabled` until the operator turns signals on. `POST /signals/companies` and `POST /signals/check` accept an `Idempotency-Key`.
Forms [#forms]
| Method | Path | API Permission |
| ------ | ----------------------------- | ---------------- |
| GET | `/forms` | `READ_CONTACTS` |
| GET | `/forms/config` | `READ_CONTACTS` |
| POST | `/forms` | `WRITE_CONTACTS` |
| GET | `/forms/:id` | `READ_CONTACTS` |
| PATCH | `/forms/:id` | `WRITE_CONTACTS` |
| DELETE | `/forms/:id` | `WRITE_CONTACTS` |
| GET | `/forms/:id/submissions` | `READ_CONTACTS` |
| DELETE | `/forms/:id/submissions/:sid` | `WRITE_CONTACTS` |
| GET | `/forms/:id/stats` | `READ_CONTACTS` |
| GET | `/forms/domain` | `READ_CONTACTS` |
| PUT | `/forms/domain` | `WRITE_CONTACTS` |
| POST | `/forms/domain/verify` | `WRITE_CONTACTS` |
| GET | `/forms/:id/links/:contactID` | `WRITE_CONTACTS` |
| POST | `/forms/:id/assets/:kind` | `WRITE_CONTACTS` |
| DELETE | `/forms/:id/assets/:kind` | `WRITE_CONTACTS` |
Hosted lead-capture forms; see the [forms guide](/guides/forms/). A form's `redirect_url` must be on one of the workspace's own domains when it is set or changed (`redirect_target_not_own_domain` otherwise), and a form with one carries `redirect_url_active`, `false` when the saved address no longer qualifies and visitors see the success message instead. Contact scopes cover them because a form exists to create contacts. Minting a personalized link is a `GET` on top of an upsert, so retries always return the same token. The `/forms/domain` routes are the workspace-wide custom forms domain and additionally need the `manage_settings` organization permission for JWT callers; `PUT` resolves the record as part of saving, and only a verified domain is ever used to build a URL. A new domain verifies only with the workspace's ownership `TXT` record beside the `CNAME`; the status carries it as `txt_name` and `txt_value`, and a domain another workspace holds is refused with `forms_domain_taken`. On the custom domain the forms service serves only that workspace's forms. The public page (`/f/:public_id`), its submit endpoint and the embed loader (`/forms.js`) are served by the standalone forms service on its own host (`FORMS_DOMAIN`), not the API origin, and take no authentication; the unguessable public id is the capability, and the JSON endpoints additionally require the render token the page shell carries.
Lead sync [#lead-sync]
Saved Google Sheets sources that upsert contacts on demand. Gated under the contact write scope because a sync ultimately writes contacts. Nothing syncs on a timer: a source only runs when `/lead-sync/sources/:id/sync` is called.
| Method | Path | API Permission |
| ------ | ---------------------------------------------- | ---------------- |
| GET | `/lead-sync/google/connection` | `WRITE_CONTACTS` |
| POST | `/lead-sync/google/spreadsheet` | `WRITE_CONTACTS` |
| POST | `/lead-sync/google/preview` | `WRITE_CONTACTS` |
| GET | `/lead-sync/sources`, `/lead-sync/sources/:id` | `WRITE_CONTACTS` |
| POST | `/lead-sync/sources` | `WRITE_CONTACTS` |
| PATCH | `/lead-sync/sources/:id` | `WRITE_CONTACTS` |
| DELETE | `/lead-sync/sources/:id` | `WRITE_CONTACTS` |
| POST | `/lead-sync/sources/:id/sync` | `WRITE_CONTACTS` |
A source's `column_mapping` is validated when the source is written, not on its next sync, so a mapping with no `email` column or an unusable custom-field name is a `400` on create or update. See [integrations](/api/reference/integrations/).
Unibox [#unibox]
| Method | Path | API Permission |
| ------ | ---------------------------------- | ------------------------------------------------------------- |
| GET | `/unibox` | `READ_UNIBOX` |
| GET | `/unibox/count` | `READ_UNIBOX` |
| GET | `/unibox/thread` | `READ_UNIBOX` |
| GET | `/unibox/:id` | `READ_UNIBOX` |
| PATCH | `/unibox/seen` | `WRITE_UNIBOX` |
| PATCH | `/unibox/folder` | `WRITE_UNIBOX` |
| POST | `/unibox/reply` | `WRITE_UNIBOX` (plus `READ_UNIBOX` with `forward_message_id`) |
| POST | `/unibox/reply/draft` | `READ_UNIBOX` |
| GET | `/unibox/compose/candidates` | `READ_UNIBOX` |
| POST | `/unibox/compose` | `WRITE_UNIBOX` |
| POST | `/unibox/compose/draft` | `READ_UNIBOX` |
| GET | `/unibox/drafts` | `READ_UNIBOX` |
| PUT | `/unibox/drafts/:id` | `WRITE_UNIBOX` |
| DELETE | `/unibox/drafts/:id` | `WRITE_UNIBOX` |
| GET | `/unibox/agent-drafts` | `READ_UNIBOX` |
| POST | `/unibox/agent-drafts/:id/approve` | `WRITE_UNIBOX` |
| POST | `/unibox/agent-drafts/:id/discard` | `WRITE_UNIBOX` |
`PATCH /unibox/folder` re-files into `inbox`, `archive` or `trash`. Name the messages with `email_ids`, the conversations with `thread_ids`, or both; up to 500 of each. Prefer `thread_ids` when you have one: filing part of a conversation leaves it listed, because a thread shows wherever any message of it still sits. The move is then relayed to each mailbox with `relay_folder_moves` on (the default): the provider's copy is archived, moved to its trash, or put back in its inbox, after the response and best-effort, and the next sync will not undo a filing either way, because the provider's placement is tracked separately and followed only when the provider itself moves the message. `sent`, `drafts` and `spam` are placements a provider reaches rather than somewhere a person files mail, so they are rejected with a `400`. See [filing a conversation](/guides/unibox/#filing-a-conversation).
`PATCH /unibox/seen` takes the same two forms: `email_ids` for individual messages, `thread_ids` for whole conversations. `folder` sweeps one folder instead and cannot be combined with either. Unread by conversation marks only its newest received message (preferring one outside spam and trash), or its newest sent copy if it has no received message; otherwise sent copies stay read. Drafts are never marked unread. Explicit `email_ids` and `folder` sweeps never mark sent or draft copies unread.
`GET /unibox` lists every working folder by default. Spam, trash and archive stay out, so a conversation you file leaves every view rather than only the Inbox folder; pass `include_archived=true` for the All mail behaviour, or `folder=archive` to read the folder itself.
`POST /unibox/snooze` accepts `thread_id` for one conversation or `thread_ids` for up to 500. The single form answers with the snooze row, as before; the bulk form answers with `data`. `DELETE /unibox/snooze?thread_id=` accepts a comma-separated list.
`POST /unibox/reply` with `forward_message_id` forwards a stored message, which discloses it, so the key also needs `READ_UNIBOX` and, when it is restricted to certain mailboxes, the mailbox the message belongs to. See [Forwarding a message](/api/reference/unibox/#forwarding-a-message).
`POST /unibox/reply/draft` returns an AI-drafted reply (it never sends) grounded in the thread, the contact, the campaign step the thread answers, and the [campaign brain](/guides/campaign-brain/) that applies, else your [voice profile](/guides/unibox/#ai-drafts). When a campaign or brain applied, the response carries `grounding`: what the draft read (names and counts, never text) and any `flags`. A brain that cannot be read answers `503 brain_unavailable` before anything is charged. It charges AI credits; see [AI credits](/guides/ai-credits/). An `Idempotency-Key` pays for one draft: a retry replays the first response, and a key whose credits were given back after a model failure is charged again.
`POST /unibox/compose/draft` returns a grounded AI draft for a new email (it never sends): the recipient's contact record, correspondence history, and the workspace voice profile feed the prompt, and the response carries either `text` or a clarifying `question` plus a `grounding` report. When the workspace default brain applies, `grounding.brain` holds what the draft read and any flags. Charges AI credits like the reply draft; see [AI credits](/guides/ai-credits/).
`POST /unibox/compose` sends a brand-new outbound email (not a reply). `body_html` goes out as written; with `body_plain` left empty, the plain-text part is rendered from it, which `POST /unibox/reply` does too. Omit `email_account_id` (or pass `"auto"`) and the backend picks the best mailbox for the first recipient; the response reports `account_id`, `account_email`, `auto`, and a `picked_reason`. Recipients on the workspace suppression list are rejected with a `400` before anything queues. `GET /unibox/compose/candidates?to=` returns every active mailbox scored for that recipient (conversation history, remaining daily budget, domain-auth health) plus the resolved contact and suppression state; see [composing email](/guides/unibox/#composing).
The `/unibox/drafts` endpoints hold autosaved compose drafts, scoped to the calling user within the organization. The draft id is client-generated, so `PUT` is idempotent (safe for debounced autosave and retries); deleting a missing draft is a no-op. A draft carries `body` (the plain text) and `body_html`, which is empty for a plain-text draft; each is capped at 100,000 characters.
`GET /emails/:id/auth-check` runs a live SPF/DKIM/DMARC lookup on the mailbox's sending domain and reports it without changing anything. `POST /emails/:id/auth-check` runs the same lookup and records the verdict against every active mailbox on that domain, which is what clears the send gate after a DNS fix, so it needs `WRITE_EMAILS` rather than `READ_EMAILS`. The write takes no `Idempotency-Key`: it is derived entirely from public DNS with no request body, so repeating it converges on the same result. See [domain authentication](/guides/deliverability/#domain-authentication).
`GET /emails/:id/track` reports the mailbox's stored tracking domain plus the `CNAME` value this deployment expects (`cname_target`, taken from its `TRACKING_DOMAIN`), and does no DNS work. It also carries the ownership `TXT` record (`txt_name`, `txt_value`) a host the workspace has not verified before needs beside the `CNAME`; until it is published the status is `proof_missing`. `PATCH /emails/:id/track` sets the domain and resolves it once; `POST /emails/:id/track/verify` re-resolves the saved one and records the verdict, which is what makes a record that has finished propagating start being used. Both writes are derived from public DNS with no request body, so they take no `Idempotency-Key`. Only a verified domain is used at send time; until then opens and clicks go through the shared tracking host. See [custom tracking domain](/guides/mailboxes/#custom-tracking-domain).
`POST /emails/:id/hold` keeps a mailbox out of campaign sending until `POST /emails/:id/release` puts it back; warmup is unaffected and the automatic rest logic never releases a hold. `release` is also the manual exit for a mailbox that is `resting` automatically. Both are bodyless and idempotent, so they take no `Idempotency-Key`. See [holding a mailbox yourself](/guides/mailboxes/#holding-a-mailbox-yourself).
`GET /emails/allowance` reports how many mailboxes the workspace holds (`used`), how many it may hold (`allowance`, `null` for unlimited), `remaining`, and the `basis` of the number: `fair_use` (the plan's daily sends divided by `sends_per_mailbox`), `plan`, `override` (an approved request), `free`, or `unlimited`. `pending_request` is the open limit-increase request for mailboxes, if any. Every connect path refuses with `mailbox_allowance_reached` once `remaining` is `0`. See [mailbox allowance](/guides/mailboxes/#mailbox-allowance).
`GET /emails/:id/identity` reports which addresses the mailbox's provider will let it send as, which one it uses, and whether its signature was imported or written here; it contacts no provider. `POST /emails/:id/identity/refresh` re-reads that list from the provider and stores it, and with `import_signature` also replaces the stored signature with the one configured at the provider. Storing the list is what a `send_as_email` choice is validated against, so the refresh needs `WRITE_EMAILS` rather than `READ_EMAILS`; it takes no `Idempotency-Key` because it writes exactly what the provider currently says. Gmail only. See [sending identity](/guides/mailboxes/#sending-identity).
`GET /emails/:id/sync` reports, alongside the import state and budget, `skip_folders` (the folders the mailbox's sync leaves alone) and `folders` (what the worker last listed on the server, each with its `name` and the canonical `folder` it files under, INBOX first; empty for Gmail and Outlook). `PUT /emails/:id/sync` takes `{"skip_folders": [...]}` and replaces the list: names as the server lists them, matched without regard to case, each covering its subfolders. Mail already stored from a newly skipped folder is removed, the mailbox is re-shipped to its worker so the change applies on the next pass, and the response is the list as stored. It refuses `INBOX` and any sent, drafts, spam, trash or archive folder with `400 invalid_sync_folder`, as it does a list of more than `50` names or a mailbox that is not IMAP. The body is the desired state, so it takes no `Idempotency-Key`. See [folders you do not want synced](/guides/mailboxes/#folders-you-do-not-want-synced).
`GET /emails/:id/certificates` reports, for an SMTP/IMAP mailbox, each server's `host`, `port`, `tls_unverified` (whether it is trusted on its own certificate rather than a certificate authority) and `tls_pin` (the SHA-256 fingerprint of the public key it is trusted on, lowercase hex). It contacts no server. A Gmail or Outlook mailbox answers `400`, since it has no certificate choice. On `POST /emails/onboarding/smtp-imap` and `PUT /emails/onboarding/smtp-imap/:id`, the `smtp` and `imap` objects accept `tls_unverified` (boolean, default false) and `tls_pin`. A server whose certificate verifies keeps normal checking whatever `tls_unverified` says; one that does not is pinned to what the connection test saw, or to `tls_pin` when it is given and matches. See [servers with their own certificate](/guides/mailboxes/#servers-with-their-own-certificate).
`PATCH /emails/:id` accepts `save_to_sent` (boolean) on SMTP/IMAP mailboxes: when true, which is the default, the worker files a copy of each outbound message in the mailbox's Sent folder. It has no effect on Gmail and Outlook mailboxes, whose APIs file their own copy. See [keeping a copy of sent mail](/guides/mailboxes/#keeping-a-copy-of-sent-mail).
`PATCH /emails/:id` also accepts `relay_folder_moves` (boolean, default true), on every provider: when true, filing a conversation with `PATCH /unibox/folder` moves it in the mailbox too. See [filing in the mailbox](/guides/mailboxes/#filing-in-the-mailbox).
The same `WRITE_EMAILS` mailbox PATCH accepts `test_mode` (`diagnostic`, `off`, `legacy`), independent `test_send_enabled`/`test_receive_enabled`, positive `shared_daily_limit`/`rolling_recipient_limit`, and `send_recovery_resolution`. Repair resolution binds `held_task_id`/`held_reason` and requires either `authentication_repaired` with a newer definitive successful same-mailbox outbound `evidence_task_id`, or `operator_provider_confirmation` with a same-mailbox definitive applied `evidence_task_id` and non-empty `confirmation_reference`. Fresh inbox sync alone is not evidence. For `held_reason: "unknown"`, explicit provider confirmation accepts `operator_confirmed_sent` (requires `message_id`, optional `provider_msg_id`/`thread_id`) or `operator_confirmed_not_sent` (no message/thread handles), with a non-empty `confirmation_reference` and no `evidence_task_id`. This queues an audited normal send result, not an immediate hold reset. The consumer reconciles it before reopening admission; other unknown tasks remain held. A timeout or missing Sent copy never permits automatic retry. Existing NULL participation remains legacy; new mailboxes default off. See [send safety and exact resolution requirements](/development/send-safety/).
`DELETE /emails/:id` releases the mailbox on AY Inbox Cloud before removing the local mailbox. An enrolled mailbox's stored credential comes out of the pool, and a cloud-managed mirror's claim is released so the mailbox returns to the cloud workspace and can be adopted again. If the cloud cannot confirm the release, the delete returns `409 mailbox_cloud_unenroll_failed` and keeps the mailbox record so the request can be retried safely. AY Inbox attempts to restore the mailbox onto its worker immediately, and the worker reconciler may restore it later if that attempt fails. See [mailboxes](/guides/mailboxes/).
`GET /unibox` and `GET /unibox/thread` return message previews: each row carries `snippet`, a one-line summary, not the message body. Read a full message with `GET /unibox/:id`, which returns `body_plain` plus `body_html`. The HTML is sanitized before it leaves the API (scripts, event handlers, embedded frames, and unsafe URL schemes are removed), so it is safe to render, and links carry `target="_blank"` with `rel="noopener"`. AY Inbox open-tracking pixels are also removed from this display copy, including quoted history, so rendering it does not record a campaign open. Stored and delivered copies keep their pixels. `body_truncated` is `true` on the rare message whose stored body could not be read, where `body_plain` falls back to the snippet. The same response carries the full envelope (`from`, `to`, `cc`, `bcc`, `ReplyTo`, `date`, `internal_date`, `message_id`, `in_reply_to`, `size`), the mailbox it belongs to (`email_id`) and its canonical `folder`.
`GET /unibox` also accepts `address=` (matches sender or recipient, for "every conversation with this person") and `direction=sent|received` (resolved against your own mailbox addresses).
The `agent-drafts` endpoints back the [inbox agent](/guides/inbox-agent/): the agent drafts a suggested reply on an inbound human reply and holds it here for review. `GET` lists the pending drafts, each with its `grounding` (what it read and any `flags`); `approve` sends one (optionally with an edited `body`) through the normal reply path and is safe to retry with an `Idempotency-Key`; `discard` dismisses it. Approving is the only path that sends. An API key or OAuth caller approving a draft whose `grounding.flags` is not empty gets `409 draft_flagged` until it sends `"acknowledge_flags": true` (with a new `Idempotency-Key`, or none), and an edited body still needs it. A caller without `WRITE_CAMPAIGNS` is held and answered only on the flags the list shows it. A signed-in member is never held.
Templates and CRM [#templates-and-crm]
| Method | Path | API Permission |
| ----------------- | ------------------------------------------------------------ | ---------------------------------------- |
| GET | `/templates`, `/templates/:id` | `READ_TEMPLATES` |
| POST | `/templates/score` | `READ_TEMPLATES` |
| POST | `/templates/analyze` | `WRITE_TEMPLATES` (it spends AI credits) |
| POST/PATCH/DELETE | `/templates[/:id]` | `WRITE_TEMPLATES` |
| GET | `/crm/pipelines`, `/crm/pipelines/:id` | `READ_CRM` |
| POST/PATCH/DELETE | `/crm/pipelines[/:id][/stages[/:stageId]]` | `WRITE_CRM` |
| GET | `/crm/deals`, `/crm/deals/:id` | `READ_CRM` |
| POST/PATCH/DELETE | `/crm/deals[/:id]` | `WRITE_CRM` |
| GET | `/crm/tasks`, `/crm/tasks/:id` | `READ_CRM` |
| POST/PATCH/DELETE | `/crm/tasks[/:id]` | `WRITE_CRM` |
| PATCH/DELETE | `/crm/tasks` (bulk, over an id list or a whole filter) | `WRITE_CRM` |
| GET | `/crm/task-types` | `READ_CRM` |
| POST/PATCH/DELETE | `/crm/task-types[/:id]` | `WRITE_CRM` |
| GET | `/crm/settings`, `/crm/metadata`, `/crm/owners`, `/crm/sync` | `READ_CRM` |
| PUT | `/crm/settings` | `INTEGRATIONS` |
| PUT | `/crm/owners/:externalId` | `INTEGRATIONS` |
| POST | `/crm/sync`, `/crm/sync/retry`, `/crm/sync/discard` | `INTEGRATIONS` |
| GET/POST | `/crm/backfill` | `INTEGRATIONS` |
| GET | `/crm/contacts/:id` | `READ_CRM` |
| POST | `/crm/contacts/:id/refresh` | `READ_CRM` |
| POST | `/crm/contacts/:id/link` | `WRITE_CRM` |
| PATCH | `/crm/contacts/:id` | `WRITE_CRM` |
| GET | `/crm/lists` | `READ_CRM` |
| POST | `/crm/lists/preview`, `/crm/lists/import` | `WRITE_CONTACTS` |
The `/crm/settings` through `/crm/lists` routes are CRM provider mode ([HubSpot](/guides/hubspot/) or [Pipedrive](/guides/pipedrive/)), and act on the CRM the workspace runs on. For a dashboard session they gate on `view_contacts` to read, `manage_contacts` to edit a contact's CRM record or import a list, and `manage_settings` to change the mode, match owners, run a sync or copy records. `POST /crm/sync/retry`, `POST /crm/sync/discard` and `POST /crm/backfill` are naturally safe to retry: a requeued job is not queued twice and a copied record is never copied again. While HubSpot or Pipedrive is the workspace's CRM, writes to pipelines, stages and task types answer `409 crm_managed_externally`. See [CRM](/api/reference/crm/#crm-provider-mode).
Analytics and audit [#analytics-and-audit]
| Method | Path | API Permission |
| ------ | ----------------------------------------------------------------------------------------------------------------------- | ----------------- |
| GET | `/analytics/*` (dashboard, direct, inbox-tagging, deliverability, warmup, warmup/placement, campaigns, accounts, usage) | `READ_ANALYTICS` |
| GET | `/audit-logs` | `READ_AUDIT_LOGS` |
Analytics reads use the selected workspace for JWT callers and the key's workspace for API-key callers. This includes warmup and usage totals, so teammates see the same workspace history regardless of which member connected a mailbox or created a campaign.
The Cloud warmup reports below and the `/pool-link/instance/analytics/*` routes belong to the warmup pool link, which this build switches off (`config.PoolLinkEnabled` and `config.CloudLinkEnabled` in `internal/config/links.go`). The routes are not registered and answer `404`; the text stays for reference. See [AY Inbox Cloud](/guides/ayinbox-cloud/).
`GET /analytics/warmup` and `GET /analytics/warmup/placement` include detailed Cloud warmup reports for enrolled mailboxes on a linked self-hosted instance, alongside local warmup history. The optional `email_id` is always the local mailbox ID; workspace reports request only that workspace's enrollments. Cloud failures are returned as errors, not empty or partial reports. Daily warmup stats include `active`, whether that date had a warmup plan, so combining sources counts each active UTC date once.
Cloud exposes `POST /pool-link/instance/analytics/warmup` and `POST /pool-link/instance/analytics/warmup/placement` for instance tokens only, not API keys. Both accept `{ "remote_ids": ["uuid"], "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }`, with 1 to 100 enrolled remote IDs and up to 366 inclusive UTC days. Invalid ranges or batch sizes return `400`; any ID not enrolled by the calling instance refuses the whole request with `pool_link_mailbox_not_found`. The first returns daily counts, including `active`; the second returns raw `daily`, `hosts`, `sent`, `unconfirmed` and `windows` counts with instance-side remote IDs. Daily placement includes the lookback before `from` needed for rolling rates, hosts and send counts cover the requested range, and windows cover the current trailing window.
`GET /analytics/inbox-tagging` accepts `limit`, opaque `cursor`, and `needs_review` query parameters and returns `data`, aggregate `summary`, and `pagination`. Each row carries `actions`, the list of what the verdict was allowed to do (`hold`, `stop`, `task`, `suppress`), and `summary.acted` counts the rows that did anything. `return_date` (`YYYY-MM-DD`, or `null`) is the out-of-office return date the model was asked to confirm, with its answer under `answers.return_date`. Invalid cursors, limits, or booleans return `400`.
`GET /analytics/accounts` returns account health and usage in the standard `data` plus `pagination` envelope with an opaque `cursor`. Pass `email_ids` (comma-separated, up to 200) to ask only for the mailboxes a page shows, or `limit` (`1`-`1000`, default `1000`) and `cursor` to walk the whole inventory. Per-mailbox reads are batched across the page, so a page's cost does not grow with the total inventory, and a workspace with more mailboxes than one page reaches the rest through `next_cursor` instead of having them silently dropped. Invalid cursors, limits, or ids return `400`.
Inbox placement tests [#inbox-placement-tests]
A [placement test](/guides/placement-tests/) sends real mail from one of the workspace's mailboxes, so starting and cancelling one takes the same permission as starting a campaign, while reading results is an analytics read. Everything here is scoped to the workspace: a test, a sending mailbox, a campaign, a step and a contact are each checked to belong to it before anything is sent.
| Method | Path | API Permission |
| ------ | ------------------------------------ | ---------------- |
| GET | `/placement/overview` | `READ_ANALYTICS` |
| GET | `/placement/tests` | `READ_ANALYTICS` |
| GET | `/placement/tests/:id` | `READ_ANALYTICS` |
| POST | `/placement/tests` | `SEND_CAMPAIGNS` |
| POST | `/placement/tests/:id/cancel` | `SEND_CAMPAIGNS` |
| GET | `/placement/seeds` | `READ_EMAILS` |
| PUT | `/placement/seeds/:email_account_id` | `WRITE_EMAILS` |
| GET | `/placement/batches` | `READ_ANALYTICS` |
| GET | `/placement/batches/:id` | `READ_ANALYTICS` |
| GET | `/placement/batches/:id/senders` | `READ_ANALYTICS` |
| POST | `/placement/batches/preview` | `SEND_CAMPAIGNS` |
| POST | `/placement/batches` | `SEND_CAMPAIGNS` |
| POST | `/placement/batches/:id/cancel` | `SEND_CAMPAIGNS` |
| GET | `/placement/coverage` | `READ_ANALYTICS` |
For session callers the matching organization permissions are **View analytics** for the reads (tests, batches, a batch's senders and coverage), **Send campaigns** for starting, previewing and cancelling a test or a batch, **View campaigns** for listing seed inboxes and **Manage mailboxes** for marking one. The campaign's placement monitor (`/campaigns/:id/placement-monitor`, listed under campaigns above) is read with **View campaigns** and changed with **Send campaigns**.
A key restricted to certain mailboxes can only start a test from one of them and only sees and marks those mailboxes as seeds. `POST /placement/tests` accepts an `Idempotency-Key`; `PUT /placement/seeds/:email_account_id` and `PUT /campaigns/:id/placement-monitor` state an absolute value, so a retry lands on the same state. `GET /placement/tests` takes `limit` (`1` to `100`, default `25`), an opaque `cursor` and an optional `campaign_id`, and returns `data` plus `pagination`; an invalid cursor or limit is a `400`. It leaves out the tests a batch started, which are read through their batch.
A [placement batch](/guides/placement-tests/#testing-a-fleet-with-batches) runs the same test from many mailboxes. `POST /placement/batches` takes the copy, panel, tracking and pace a single test takes, plus exactly one of `sender_account_ids` or `sender_scope` (`{"type": "campaign", "campaign_id": ...}` or `{"type": "workspace"}`, with optional `providers`, `domains`, `tag_ids`, `include_inactive` and `untested_days`), an optional `sample`, `on_unavailable` (`defer` or `skip`) and `max_credits` for the whole batch. It answers `201` with the batch `queued` as soon as the senders are written down; the backend starts them a few at a time. `POST /placement/batches/preview` takes the same body and returns the counts it would come to (senders, tests, the most copies sent, free and paid tests, credits) without starting anything or writing a row. A key restricted to certain mailboxes can only name those in `sender_account_ids` (another is a `403`), and a server-side scope resolves to those alone. `POST /placement/batches` accepts an `Idempotency-Key`; cancelling states an end state, so a retry answers `placement_batch_not_running` and changes nothing. `GET /placement/batches` and `GET /placement/batches/:id/senders` take `limit` and `cursor` like the tests list; the senders list also takes `sort` (`worst`, the default, `best`, `email` or `status`), `status` and `q` (a substring of the address), and an unknown value of any of them is a `400`. See the [placement endpoint reference](/api/reference/placement/).
Advisor [#advisor]
Recommendations about deliverability, mailbox configuration, warmup, campaign performance, copy, and list quality. See the [Advisor guide](/guides/advisor/).
`GET /advisor/recommendations` returns open and applied findings by default. Pass `status=open` for outstanding suggestions only, `status=applied` for applied fixes, or `status=resolved` for findings cleared by a recheck. Repeat `status` to request several states. The dashboard requests open findings so applied fixes leave its suggestions immediately. Campaign, step and mailbox changes trigger a background recheck that clears findings which no longer apply.
Reads are an analytics read of the workspace's sending posture. Applying or undoing a fix has no scope of its own: the change runs through the tool the fix actually uses and is refused if the caller lacks that tool's permission, so a key that can read recommendations cannot use them to make changes it could not make directly.
| Method | Path | API Permission |
| ------ | --------------------------------------- | -------------------------------------------------------------- |
| GET | `/advisor/recommendations` | `READ_ANALYTICS` |
| GET | `/advisor/summary` | `READ_ANALYTICS` |
| GET | `/advisor/settings` | `READ_ANALYTICS` |
| POST | `/advisor/refresh` | `READ_ANALYTICS` |
| POST | `/advisor/recommendations/:id/snooze` | `READ_ANALYTICS` |
| POST | `/advisor/recommendations/:id/dismiss` | `READ_ANALYTICS` |
| POST | `/advisor/recommendations/:id/feedback` | `READ_ANALYTICS` |
| POST | `/advisor/recommendations/:id/apply` | `READ_ANALYTICS`, plus the permission of the underlying change |
| POST | `/advisor/recommendations/:id/undo` | `READ_ANALYTICS`, plus the permission of the underlying change |
Apply and undo run the fix under the key's own scopes, and a key limited to certain mailboxes can only apply or undo a fix for one of them (`403` otherwise). Changing Advisor settings (`PATCH /advisor/settings`) is JWT only, alongside the rest of organization settings. Silencing checks for a whole workspace is governance, and no read scope should be able to do it. The same applies to `POST /advisor/recommendations/:id/agent-fix`, which is JWT only and needs `USE_AI`: it acts as a named member and spends credits, and no API scope should let a key rewrite a workspace's campaigns unattended.
API key self-service [#api-key-self-service]
| Method | Path | API Permission |
| ------ | ------------------------- | ---------------------------- |
| GET | `/api-keys` | `API_KEYS` |
| POST | `/api-keys` | `API_KEYS`, not OAuth tokens |
| GET | `/api-keys/permissions` | `API_KEYS` |
| GET | `/api-keys/:id` | `API_KEYS` |
| PATCH | `/api-keys/:id` | `API_KEYS`, not OAuth tokens |
| DELETE | `/api-keys/:id` | `API_KEYS`, not OAuth tokens |
| DELETE | `/api-keys/:id/permanent` | `API_KEYS`, not OAuth tokens |
| DELETE | `/api-keys/self` | none |
`DELETE /api-keys/:id/permanent` deletes a key that has already been revoked or has expired, taking its usage logs with it. A key that could still authenticate gets a `409`, because revoking is what records that a credential was ended and why. See [Ending a key](/api/authentication/).
`POST /api-keys` and `PATCH /api-keys/:id` require a recent confirmation (`POST /auth/reauth`) when called from a signed-in session, because a key outlives the session that made it and a stolen browser token should not be able to leave one behind or widen one. An API key calling them is unaffected: it has no session and no second factor to present, it was itself minted from a confirmed session, and the `API_KEYS` scope is the explicit grant that governs it. Automation and the CLI keep working.
Creating, editing, revoking and deleting keys is for a signed-in member or an API key; an OAuth app token gets `403` `oauth_token_not_allowed`. A new or edited key stays within its creator: a member cannot give it a permission their role does not cover, and an API key cannot give it a permission, mailbox or IP address the calling key does not have (`403` `api_key_permissions_exceed_caller`). See [what a role can delegate](/api/permissions/#what-a-role-can-delegate). `GET /api-keys/permissions` reports the caller's bound as `grantable`.
`DELETE /api-keys/self` revokes the key the request was made with, and is the one route here that needs no scope. A credential must always be able to end itself: requiring `API_KEYS` to sign out would leave a read-only key on a laptop someone is handing back live, which is what [`ayinbox auth logout`](/api/cli/) promises to prevent. A JWT caller gets a `400`: there is no key in that request to end, only a session, which `POST /auth/logout` ends.
OAuth apps [#oauth-apps]
Registering and managing the OAuth apps your workspace owns. The flow itself (authorize, token, revoke) is listed under JWT only and Public below. Every route here, and `POST /oauth/application-logo`, refuses an OAuth app token with `403` `oauth_token_not_allowed`.
| Method | Path | API Permission |
| ------ | ----------------------------------------------- | -------------- |
| GET | `/oauth/applications` | `API_KEYS` |
| POST | `/oauth/applications` | `API_KEYS` |
| GET | `/oauth/applications/:id` | `API_KEYS` |
| PATCH | `/oauth/applications/:id` | `API_KEYS` |
| DELETE | `/oauth/applications/:id` | `API_KEYS` |
| POST | `/oauth/applications/:id/rotate-secret` | `API_KEYS` |
| POST | `/oauth/applications/:id/logo` | `API_KEYS` |
| DELETE | `/oauth/applications/:id/logo` | `API_KEYS` |
| GET | `/oauth/applications/:id/webhook-secret` | `API_KEYS` |
| POST | `/oauth/applications/:id/webhook-secret/rotate` | `API_KEYS` |
| GET | `/oauth/applications/:id/webhook-endpoints` | `API_KEYS` |
| GET | `/oauth/applications/:id/webhook-deliveries` | `API_KEYS` |
| GET | `/oauth/applications/:id/listing` | `API_KEYS` |
| PUT | `/oauth/applications/:id/listing` | `API_KEYS` |
| DELETE | `/oauth/applications/:id/listing` | `API_KEYS` |
The `listing` routes publish an app to the [community directory](/api/oauth/#publish-to-the-community-directory). `PUT` replaces the whole listing and `DELETE` succeeds when there is nothing to remove, so both are safe to retry. Browsing the directory is `GET /integrations/community` and `GET /integrations/community/:slug`, under `/integrations/*` below.
Operations [#operations]
| Method | Path | API Permission |
| --------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| GET/PATCH | `/outreach/settings` | `WRITE_CAMPAIGNS` |
| GET/PUT | `/outreach/consent` | `WRITE_CAMPAIGNS` |
| POST | `/deliverability/events` | `WRITE_CAMPAIGNS` |
| GET | `/suppressions` | `READ_CONTACTS` |
| POST | `/suppressions` | `WRITE_CONTACTS` |
| DELETE | `/suppressions/:id` | `WRITE_CONTACTS` |
| GET | `/tasks/dlq` | `SEND_CAMPAIGNS` |
| POST | `/tasks/dlq/:id/replay` | `SEND_CAMPAIGNS` |
| GET/POST/PATCH/DELETE | `/webhooks[/:id]` | `WEBHOOKS` |
| POST | `/webhooks/:id/rotate-secret` | `WEBHOOKS` |
| POST | `/webhooks/:id/verify` | `WEBHOOKS` |
| GET | `/webhooks/event-types` | `WEBHOOKS` |
| GET | `/webhooks/deliveries` | `WEBHOOKS` |
| GET | `/webhooks/:id/deliveries` | `WEBHOOKS` |
| POST | `/webhooks/deliveries/:deliveryId/redeliver` | `WEBHOOKS` |
| GET | `/webhooks/throttle-drops` | `WEBHOOKS` |
| GET/POST/DELETE | `/integrations/*` (except `/integrations/slack/*`, which is [JWT only](#slack), and `/integrations/bookings`) | `INTEGRATIONS` |
| GET | `/integrations/bookings` | `READ_CONTACTS` |
| GET/PUT | `/integrations/salesforce/:id/settings` | `INTEGRATIONS` |
| GET | `/integrations/salesforce/:id/overview`, `/metadata`, `/users`, `/list-views`, `/campaigns`, `/activity` | `INTEGRATIONS` |
| POST | `/integrations/salesforce/:id/import/preview` | `INTEGRATIONS` |
| GET/POST/PATCH/DELETE | `/integrations/salesforce/:id/import-sources[/:sourceId]` | `INTEGRATIONS` |
| POST | `/integrations/salesforce/:id/import-sources/:sourceId/run` | `INTEGRATIONS` |
| POST | `/integrations/salesforce/:id/activity/retry`, `/sync-now` | `INTEGRATIONS` |
| GET | `/contacts/:id/salesforce` | `READ_CRM` |
| POST | `/contacts/:id/salesforce/sync` | `INTEGRATIONS` |
| DELETE | `/contacts/:id/salesforce/links/:linkId` | `INTEGRATIONS` |
| GET | `/integrations/apollo/:id`, `/lists` | `INTEGRATIONS` |
| PUT | `/integrations/apollo/:id/key` | `INTEGRATIONS` |
| POST | `/integrations/apollo/:id/import/preview` | `INTEGRATIONS` |
| GET/POST/PATCH/DELETE | `/integrations/apollo/:id/import-sources[/:sourceId]` | `INTEGRATIONS` |
| POST | `/integrations/apollo/:id/import-sources/:sourceId/run` | `INTEGRATIONS` |
| GET | `/integrations/apollo/:id/enrichments[/:runId]` | `INTEGRATIONS` |
| POST | `/integrations/apollo/:id/enrichments` | `INTEGRATIONS` and `BULK_CONTACTS` |
| GET | `/integrations/looot/lead-jobs[/:jobId]` | `INTEGRATIONS` |
| POST | `/integrations/looot/lead-jobs` | `INTEGRATIONS` and `BULK_CONTACTS`, plus `SEND_CAMPAIGNS` with a `campaign_id` that is sending |
| GET/PATCH | `/integrations/clay/:id` | `INTEGRATIONS` |
| GET/POST/PATCH/DELETE | `/automations[/:id]` | `INTEGRATIONS` |
| PATCH | `/automations/:id/layout` | `INTEGRATIONS` |
`/outreach/consent` is the workspace's list of countries whose contacts need [prior consent](/guides/contacts-crm/#prior-consent) before any campaign email: `{"countries": ["DE", "MA"]}`, ISO 3166-1 alpha-2 codes, up to 300. `PUT` replaces the whole list, so a retry lands on the same state. `countries` is required: `[]` empties the list, and a body without it is a `400` rather than an empty list. An unknown code is `400 invalid_country_code`. A signed-in member needs `manage_settings`, as for `/outreach/settings`.
A signed-in member needs `manage_settings` to create, edit, enable or delete an automation, because a flow runs as the workspace; `use_integrations` is enough to list, open, test and read the run history.
Starting a [Looot lead job](/guides/looot-leads/) writes contacts and spends the instance's Looot balance, so it takes the same two scopes. A job that names a campaign which is active, finished or parked for undeliverable leads mails what it finds, so it also takes `SEND_CAMPAIGNS` (`send_campaigns` for a member) and is otherwise refused with `403` [`looot_campaign_send_required`](/api/error-codes/#looot_campaign_send_required); a draft or paused campaign needs nothing more. Starting an [Apollo](/guides/apollo/) enrichment writes contacts and spends the workspace's Apollo credits, so it needs `BULK_CONTACTS` as well as `INTEGRATIONS` (for a member, `use_integrations` and `manage_contacts`). Saving the key, imports and Clay settings need `manage_settings`; previewing and running an import need `use_integrations`. `POST /integrations/inbound/clay/:secret` is the URL a [Clay](/guides/clay/) table posts rows to. It takes no API key, because the secret in its path is the credential.
\| GET/POST/PATCH/DELETE | `/warmup/routing[/:id]` | `WARMUP_ROUTING` |
Retry safety [#retry-safety]
Mutating API requests may include an `Idempotency-Key` header. AY Inbox stores the completed response for 24 hours per organization and key. A request is identified by the credential that sent it (the signed-in user, the API key, or the OAuth authorization), the method, the concrete path including its resource ids, the query and the body. Reusing the same key for the same request replays the original response with `X-Idempotent-Replayed: true` and does not run the operation again; reusing it for anything else, including the same route on a different resource or a different credential, returns `409 Conflict`. A second request sent while the first is still running also gets `409 Conflict`. A response that carries a secret shown once (creating an API key, a webhook endpoint, an OAuth app or an integration connection, or rotating one of their secrets) is never stored: its retry answers `409` [`idempotent_secret_withheld`](/api/error-codes/) instead of running again.
The outcome is recorded even when the client disconnects after the operation went through, so retry with the same key rather than assuming it failed. If AY Inbox cannot write the outcome down, the key answers as still processing and, after ten minutes, as unknown. A request refused before it ran (`401`, `403` or `429`) does not use up its key, so the same key works once the refusal is resolved; a refusal never clears an outcome an earlier attempt already recorded. A request that ended in a server error (`5xx`), or never finished, has an unknown outcome: for the 24 hours the key is kept it answers `409` with `code: "idempotency_outcome_unknown"` and does not run again. The operation may have happened even when a read shows no trace of it yet (a send can be delivered before its Sent copy appears), so retry with a new key only once you have established that the change did not happen.
Identity [#identity]
| Method | Path | API Permission |
| ------ | ----- | ----------------------- |
| GET | `/me` | (any authenticated key) |
`GET /me` returns who the active credential belongs to: `user_id`, `email`, `name`, `organization_id`, `organization_name`, `auth_type` (`api_key`, `oauth`, or `jwt`), and the granted `scopes`. It requires no specific permission, so it is the right call for validating a connection and rendering a human-readable label. Unlike `/auth/me` (JWT only), it is reachable by API keys and OAuth tokens.
Labels [#labels]
Folders (on campaigns), tags (on mailboxes) and labels (on contacts, inbox conversations and forms, managed through the `/categories` endpoints) are three registries with the same shape. Each belongs to the **workspace**, not to whoever created it. Every member sees the same set, whoever created it. A key or a session lists each with `GET /folders`, `/tags` or `/categories`, which answer `{data, pagination}` with every entry in one page (`has_more` is always `false`); a session also gets all three from `GET /auth/me`, which is the filtered path for a member restricted to selected resources. Reading is gated like the records each registry labels, and changing one too, so each takes the API permission in the table below, or the matching JWT permission. The lists refuse a key limited to some mailboxes with `403 api_key_mailbox_limited`, since they are workspace-wide.
`position` is the order within its own registry, `0`-based and contiguous. A move returns the full new ordering. A registry holds at most `100` entries.
| Method | Path | API Permission |
| ------ | ---------------------- | ----------------------------------- |
| GET | `/folders` | `READ_CAMPAIGNS` (`view_campaigns`) |
| GET | `/tags` | `READ_EMAILS` (`view_campaigns`) |
| GET | `/categories` | `READ_CONTACTS` (`view_contacts`) |
| POST | `/folders` | `WRITE_CAMPAIGNS` |
| PATCH | `/folders/:id` | `WRITE_CAMPAIGNS` |
| PATCH | `/folders/:id/move` | `WRITE_CAMPAIGNS` |
| DELETE | `/folders/:id` | `WRITE_CAMPAIGNS` |
| POST | `/tags` | `WRITE_EMAILS` |
| PATCH | `/tags/:id` | `WRITE_EMAILS` |
| PATCH | `/tags/:id/move` | `WRITE_EMAILS` |
| DELETE | `/tags/:id` | `WRITE_EMAILS` |
| POST | `/categories` | `WRITE_CONTACTS` |
| PATCH | `/categories/:id` | `WRITE_CONTACTS` |
| PATCH | `/categories/:id/move` | `WRITE_CONTACTS` |
| DELETE | `/categories/:id` | `WRITE_CONTACTS` |
Workspace, plan and credits [#workspace-plan-and-credits]
The workspace's profile, plan, limits and AI credit balance, so an agent can check what it may spend before a daily loop. Every route here refuses a key limited to some mailboxes with `403 api_key_mailbox_limited`. For a key or an OAuth app, `GET /subscription` and `/subscription/limits` leave out the Stripe identifiers, `managed_by`, `managed_reason` and `user_email`. Every other `/organization` and `/subscription` route (members' invitations and roles writes, exports, transfer, billing changes) stays with a signed-in person; see [JWT only](#jwt-only).
| Method | Path | API Permission | Member needs |
| ------ | ------------------------------------ | ----------------- | ----------------- |
| GET | `/organization/current` | `READ_WORKSPACE` | any member |
| GET | `/organization/current/limits` | `READ_WORKSPACE` | any member |
| GET | `/organization/current/risk` | `READ_WORKSPACE` | any member |
| PATCH | `/organization/current` | `WRITE_WORKSPACE` | `manage_settings` |
| GET | `/organization/members` | `READ_WORKSPACE` | any member |
| GET | `/organization/roles` | `READ_WORKSPACE` | any member |
| GET | `/subscription` | `READ_WORKSPACE` | any member |
| GET | `/subscription/limits` | `READ_WORKSPACE` | any member |
| GET | `/subscription/trial` | `READ_WORKSPACE` | any member |
| GET | `/subscription/features` | `READ_WORKSPACE` | any member |
| GET | `/subscription/credits` | `READ_WORKSPACE` | `manage_billing` |
| GET | `/subscription/credits/transactions` | `READ_WORKSPACE` | `manage_billing` |
| GET | `/subscription/credits/usage` | `READ_WORKSPACE` | `manage_billing` |
| GET | `/subscription/credits/settings` | `READ_WORKSPACE` | `manage_billing` |
`PATCH /organization/current` also sets `product_description`, `icp_notes` and `voice_profile`, which every AI writing surface is grounded on; each is limited to 2,000 characters (`400 org_grounding_too_long`). `GET /organization/members` and `/organization/roles` answer `{data, pagination}` with every entry in one page.
A route newly opened to keys may answer `401` from a server still on the previous release for the length of a rolling deploy; retry it.
Sending domains [#sending-domains]
The tracking host per sending domain and the bare-domain redirect (see [sending domains](/guides/sending-domains/)). They act across the workspace's domains, so they refuse a key limited to some mailboxes with `403 api_key_mailbox_limited`, and the member behind a key needs `manage_emails`. `GET /emails/domains` answers `{data, pagination}` with every domain in one page.
| Method | Path | API Permission |
| ------ | --------------------------------------------- | -------------- |
| GET | `/emails/domains` | `READ_EMAILS` |
| GET | `/emails/domains/:domain/tracking-suggestion` | `READ_EMAILS` |
| POST | `/emails/domains/bulk` | `WRITE_EMAILS` |
| PUT | `/emails/domains/:domain/tracking` | `WRITE_EMAILS` |
| PUT | `/emails/domains/:domain/redirect` | `WRITE_EMAILS` |
| POST | `/emails/domains/:domain/redirect/verify` | `WRITE_EMAILS` |
| POST | `/emails/domains/:domain/redirect/website` | `WRITE_EMAILS` |
| DELETE | `/emails/domains/:domain/redirect` | `WRITE_EMAILS` |
| PUT | `/emails/domains/:domain/vendor-forwarding` | `WRITE_EMAILS` |
| POST | `/emails/domains/:domain/vendor-tracking` | `WRITE_EMAILS` |
Slack settings [#slack-settings]
The workspace's [Slack](/guides/slack/) settings. Linking a person's own Slack account stays with that person (see [Slack](#slack) below).
| Method | Path | API Permission | Member needs |
| ------ | ------------------------------- | -------------- | --------------------------------------- |
| GET | `/integrations/slack/status` | `INTEGRATIONS` | any member |
| GET | `/integrations/slack/channels` | `INTEGRATIONS` | `manage_settings` or `use_integrations` |
| PUT | `/integrations/slack/settings` | `INTEGRATIONS` | `manage_settings` |
| DELETE | `/integrations/slack/links/:id` | `INTEGRATIONS` | `manage_settings` |
AI skills [#ai-skills]
Org playbooks the AI features follow (see the [AI skills](/guides/ai-skills/) guide). Gated on `manage_settings` for JWT callers, or the `AI_AGENT` scope for API keys. Creating, editing or deleting one with an API key also needs the member who created the key to hold `manage_settings`.
| Method | Path | Permission |
| ------ | ---------------- | ------------------------------ |
| GET | `/ai/skills` | `manage_settings` / `AI_AGENT` |
| POST | `/ai/skills` | `manage_settings` / `AI_AGENT` |
| PATCH | `/ai/skills/:id` | `manage_settings` / `AI_AGENT` |
| DELETE | `/ai/skills/:id` | `manage_settings` / `AI_AGENT` |
Agent tools (REST) [#agent-tools-rest]
The AI tool registry over plain HTTP for function-calling agents that do not speak MCP (see [Agent tools](/api/agent-tools/)). A member session needs `use_ai`; a key or OAuth token is gated per tool, each by its own permission. The list reflects only what the caller may use, and send-class tools are never exposed. `?toolsets=` narrows the list.
| Method | Path | Permission |
| ------ | ---------------------- | -------------------------------------------------------------------------- |
| GET | `/ai/tools` | `use_ai` for a session; for a key, the permission of each listed tool |
| POST | `/ai/tools/:name/call` | `use_ai` for a session; for a key, the permission of the tool being called |
Reference data [#reference-data]
| Method | Path | API Permission |
| ------ | ------------ | ----------------------- |
| GET | `/plans` | (any authenticated key) |
| GET | `/timezones` | (any authenticated key) |
How coverage is kept [#how-coverage-is-kept]
Every `/v1` route answers an API key at a scope gate, or stays with a signed-in person for a recorded reason: it signs a person in or changes how they sign in, changes who can get in, moves money, is the owner's whole-workspace export or deletion, needs a person's consent in a browser, or is one person's own screen. A test probes the router with a key holding no scope on every build, so a new dashboard action cannot ship without one or the other.
JWT only [#jwt-only]
These never accept an API key. They depend on a human-bound session: billing flows, governance, OAuth onboarding, websocket bootstrap, and operational destruction.
With [multiple dashboards sharing a backend](/development/configuration/#google-sign-in-per-dashboard-deployment), password-reset and invitation emails, referral links and billing returns use the initiating browser's exact configured dashboard origin. Without a trusted origin they use the primary dashboard. Mailbox, administrator-grant, integration and Slack identity OAuth callbacks recover their target from live server-side state, never from callback query parameters. Expired or consumed routing state is not forwarded to another dashboard.
* `POST /auth/login`, `/auth/login/confirm`, `/auth/register`, `/auth/register/confirm`, `/auth/refresh`, `/auth/reset-password`, `/auth/reset-password/session`, `/auth/reset-password/confirm`
* `POST /auth/reauth` (re-prove the account holder behind a live session, for the changes that require a recent confirmation)
* `GET /auth/reauth/methods` (which ways this account can confirm: password, two-factor code, passkey, and the linked sign-in providers it can re-verify)
* `POST /auth/reauth/passkey/begin`, `/auth/reauth/passkey/finish` (confirm with one of the account's own passkeys)
* `POST /auth/reauth/sso/begin`, `/auth/reauth/sso/finish` (confirm through the Google, Apple or single sign-on identity linked to the account, in a browser window)
* `POST /auth/reauth/native/begin`, `/auth/reauth/native` (confirm with a native Sign in with Apple or Google ID token carrying the session's nonce)
* `GET /auth/config` (public deployment capabilities: which sign-in methods this backend has enabled, whether a login code step follows, whether signups are open, whether the instance still needs claiming)
* `POST /auth/app-attest/challenge`, `/auth/app-attest/keys` (the native app's [App Attest](/api/reference/account-org/#app-attest-native-apps) challenge and one-time key registration, on their own per-IP budget `APP_ATTEST_IP_RATE_LIMIT`)
* `GET /auth/instance` (JWT only: the running AY Inbox version of a self-hosted instance and whether a newer release exists, for the dashboard's version pill; a hosted deployment answers `self_hosted: false` and nothing else)
`POST /auth/register` accepts an optional `invite` field carrying an invitation token. On a deployment running `DISABLE_REGISTRATION=invite_only` it is what permits the signup, and the account is created inside the inviting organization rather than in a new one. The token must resolve to a live invitation whose email equals the submitted address, otherwise the request is refused with `invitation_invalid`. Omitting it on a closed deployment returns `registration_invite_only` or `registration_closed`. See [error codes](/api/error-codes/#registration-and-invitation-refusals).
Actions that need a recent confirmation [#actions-that-need-a-recent-confirmation]
These changes require the session to have confirmed the account holder within the last five minutes, over and above the permission they already need:
| Action | Route |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create or edit an API key | `POST /api-keys`, `PATCH /api-keys/:id` |
| Create or edit a webhook endpoint | `POST /webhooks`, `PATCH /webhooks/:id` |
| Approve an app on the OAuth consent screen | `POST /oauth/authorize` |
| Approve a CLI sign-in | `POST /auth/cli/codes/:code/approve` |
| Add a passkey | `POST /auth/passkey/register/begin`, `/finish` |
| Remove a passkey | `DELETE /auth/passkey/credentials/:id` |
| Turn on two-factor authentication | `POST /auth/2fa/enroll/start`, `/confirm` (see below for accounts with no password) |
| Transfer a workspace | `POST /organization/transfer-ownership` |
| Invite or remove a member, change a member's role or change their access scope | `POST /organization/members/invite`, `DELETE /organization/members/:id`, `PATCH /organization/members/:id`, `PUT /organization/members/:id/access` |
| Create, edit or delete a custom role | `POST /organization/roles`, `PATCH /organization/roles/:id`, `DELETE /organization/roles/:id` |
| Export or import a whole workspace | `POST /organization/current/export`, `POST /organization/current/import` |
| Schedule a workspace or account for deletion | `POST /organization/current/danger-zone/delete`, `POST /me/danger-zone/delete` |
| Approve a self-hosted instance's warmup pool link (not available in this build) | `POST /pool-link/codes/:code/approve` |
| Start a checkout, open the billing portal, change or cancel the plan, buy AI credits or change AI spend controls | `POST /subscription/checkout`, `POST /subscription/portal`, `POST /subscription/change-plan`, `POST /subscription/cancel`, `POST /subscription/credits/checkout`, `PATCH /subscription/credits/settings`, `POST /pool-link/checkout`, `POST /subscription/offers/:planId/checkout` |
| Reveal or rotate a signing secret | `POST /webhooks/:id/rotate-secret`, `GET /integrations/connections/:id/webhook-secret`, `POST /oauth/applications/:id/rotate-secret`, `GET /oauth/applications/:id/webhook-secret`, `POST /oauth/applications/:id/webhook-secret/rotate` |
| Record, use or remove an admin grant over a whole domain | `POST /emails/grants/google/finish`, `POST /emails/grants/microsoft/finish`, `POST /emails/grants/:id/connect`, `DELETE /emails/grants/:id` |
| Admin panel: issue a fleet join token, grant admin permissions, export or import any workspace, issue a tester a new password, change a login-code exemption | `POST /admin/fleet/join-token`, `POST /admin/admins/:userId/grant`, `POST /admin/organizations/:id/exports`, `POST /admin/organizations/:id/imports`, `POST /admin/testers/:id/password`, `PUT /admin/users/:id/login-code-exempt` |
Each either hands out a credential that outlives the session that created it, reveals a secret, changes who can get in, moves money, cannot be reversed by the person it was done to, or reaches a whole domain's mail. Without a confirmation they answer `403` with code `reauth_required`; confirm and retry. See [error codes](/api/error-codes/#confirmation-required).
`GET /auth/reauth/methods` says which ways the account can confirm, so a client offers only those:
```json
{
"password": false,
"totp": false,
"passkey": true,
"providers": [{ "id": "google", "label": "Google" }],
"native_providers": ["google"],
"valid_for_seconds": 300
}
```
* **Password or code:** `POST /auth/reauth` with `password` or a current two-factor or recovery `code`.
* **Passkey:** `POST /auth/reauth/passkey/begin` returns WebAuthn request `options` limited to the account's own passkeys; pass `options.publicKey` to the browser and send the assertion to `POST /auth/reauth/passkey/finish` as `credential`. The authenticator must verify the user.
* **Linked identity in a browser:** `POST /auth/reauth/sso/begin` with `provider` (one of `providers[].id`) returns `url` and `binding`. Open `url` in a window and keep `binding`. The provider returns that window to the dashboard's `/reauth/complete` with a single-use `code`, which only the session that began the flow can redeem: `POST /auth/reauth/sso/finish` with `code` and `binding`. The identity the provider verifies must already be linked to the account; another account is refused with `reauth_identity_mismatch`, never matched by email address.
* **Native app:** `POST /auth/reauth/native/begin` returns a `nonce`. Pass it unchanged as the Sign in with Apple request nonce or the Google authorization `nonce`, then send the ID token to `POST /auth/reauth/native` with `provider` (`apple` or `google`). The nonce is single-use and bound to the session.
Each succeeds with `{ "valid_for_seconds": 300 }` and confirms only the session that made the call.
This applies to session callers. An API key or OAuth token has no session to confirm and is not the threat here, so it passes straight through to the route's permission gate.
A completed sign-in counts as a confirmation for the first five minutes of the session. `POST /auth/reauth` answers an account with neither a password nor two-factor authentication `400` with code `reauth_no_factor`; it confirms with a passkey or its linked identity instead. An account with none of those signs in again.
`GET /auth/config` gained two fields: `invites_required` (boolean, true when an invitation token is needed to create an account) and `docs_url` (string, the deployment's link to the accounts and access documentation, for a client to surface next to a refusal).
`GET /auth/config` also carries `websocket_url` and `app_url` (both strings, each omitted when the instance has none). They are the realtime gateway a developer client connects to and the dashboard origin a client sends someone to. Both are served here because on a self-hosted instance the host layout is whatever the operator chose, and there is no other way to discover it: the [CLI](/api/cli/) reads them for `ayinbox events tail` and `ayinbox browse`.
`POST /getaway` is session-only and mints a ten-minute WebSocket ticket. Its `url` remains the direct gateway; the optional `proxy_path` is resolved against `/v1` for browser connections. `GET /realtime/socket/websocket` upgrades a connection using that ticket, preserving the configured realtime service's origin checks and connection limits. It accepts no ordinary access tokens, API keys or OAuth tokens. See [Realtime WebSocket](/api/realtime/).
Alongside them, `api_url` is this API's own public base (for a copyable example that names the right server), and `brand` is who the deployment says it is: `name`, and `website_url`, `website_label`, `terms_url`, `privacy_url` and `support_email`, each omitted when unset. On a self-hosted instance that configured no `EMAIL_BRAND_*` only `name` is present, and a client should render no link at all rather than substituting one of its own. See [configuration](/development/configuration/).
`GET /auth/config` also carries `gmail_oauth_connect` (boolean): whether a new Gmail mailbox may be connected with Google sign-in. Both `BOX_GOOGLE_CLIENT_ID` and `BOX_GOOGLE_CLIENT_SECRET` are required. With them set, the capability defaults to `true`; explicit `BOX_GOOGLE_OAUTH_CONNECT=false` or an invalid value disables it. When `false`, offer the app-password route (`POST /emails/onboarding/smtp-imap` against Gmail's servers) rather than start an OAuth round trip that returns `mailbox_gmail_oauth_disabled`. The dashboard additionally requires its deployment-local [frontend opt-in](/development/configuration/#google-sign-in-per-dashboard-deployment) to show Google sign-in. Existing Google sign-in mailboxes are unaffected either way.
`GET /auth/config` also carries `app_attest` (boolean): whether this server accepts an [App Attest proof](/api/reference/account-org/#app-attest-native-apps) from the native app in place of a Turnstile token on `POST /auth/login`, `/auth/register`, `/auth/reset-password` and `/auth/reset-password/confirm`. Read it with `captcha`: no captcha means nothing to send, a captcha with `app_attest` means the app sends a proof, and a captcha without it means email and password sign-in is unavailable in the app.
`GET /auth/config` also carries `billing_enabled` (boolean). It is `false` when the deployment runs with `BILLING_PROVIDER=none`, which is the self-host default: every feature is unlocked server-side, so the dashboard shows the workspace as self-hosted instead of on a free trial and hides the billing and referral pages. `self_hosted` alone does not imply this, because a self-hosted install may still run Stripe.
* `POST /auth/setup` (first-run claim: exchanges the one-time token printed at boot for the owner account. Refused once any account exists)
* `GET /auth/providers`, `POST /auth/apple`, `POST /auth/google` (native-app social sign-in)
* `POST /auth/oidc/begin`, `GET /auth/oidc/callback` (generic OpenID Connect sign-in)
* `POST /auth/google/begin`, `GET /auth/google/callback`, `POST /auth/apple/begin`, `POST /auth/apple/callback` (browser Sign in with Google and Sign in with Apple)
* `POST /auth/sso/exchange` (swaps the single-use handoff code from any of those callbacks for the session; `POST /auth/oidc/exchange` is the older name for the same endpoint)
* `POST /auth/sso/link` (completes a provider sign-in that resolved to an existing password account: takes that account's password, attaches the identity and returns the session. An issued initial password is refused here with `password_change_required`)
* `POST /auth/login/initial-password` (answers a `/auth/login` result with `password_change_required`: takes its single-use `pending_token` and the holder's own password, replaces the issued initial password, signs out other sessions and continues the sign-in in the `/auth/login` response shape. Retrying is safe: the token is spent once, and a repeat answers `password_change_expired`)
* `POST /auth/logout`, `POST /auth/logout-all`, `GET /auth/me`, `PATCH /auth/me/onboarding`
* `PUT /auth/me/product-tour` (records that the signed-in user finished or skipped the dashboard's product tour, answering `product_tour_completed_at`, which `GET /auth/me` also carries. Naturally retry-safe: a repeat keeps the first time, so it takes no `Idempotency-Key`)
* `POST /auth/me/avatar`, `DELETE /auth/me/avatar`
* `GET /auth/me/identities`, `DELETE /auth/me/identities/:provider` (the Google, Apple and single sign-on identities linked to the signed-in user, and removing one. Removal requires a [fresh confirmation](/guides/security/), ends the other sessions that signed in through that provider, and is refused with `last_sign_in_method` when it would leave no way to sign in. No `Idempotency-Key`: a repeat converges and answers `204`)
* `POST /auth/me/password/link` (emails the signed-in user a single-use link to set a password, on the same budget as `/auth/reset-password`. No `Idempotency-Key`: a repeat mails another link and spends the budget, which is the cap on retries)
* `POST /emails/onboarding/oauth/start`, `POST /emails/onboarding/oauth/finish`, `POST /emails/onboarding/smtp-imap`. `oauth/start` accepts an optional `login_hint` (an email address) that preselects that mailbox in the provider's sign-in, which is how an import's **Sign in** rows open. For Google and Microsoft dashboard flows (`return: "web"`), the browser's `Origin` is validated against exact configured dashboard origins and bound to the OAuth state; an untrusted origin answers `400` `mailbox_oauth_return_origin`. Requests without an `Origin` retain primary-dashboard routing while their state is live
* `POST /emails/onboarding/smtp-imap/bulk` (up to `50` SMTP/IMAP rows in `accounts`, answered `200` with a per-row `status` of `connected`, `skipped` or `failed` and a `code`; rows past the workspace's [mailbox allowance](/guides/mailboxes/#mailbox-allowance) fail with `mailbox_allowance_reached` before any credential is dialled. Naturally retry-safe: an already connected mailbox is `skipped`, so it takes no `Idempotency-Key`)
* The [mailbox import](/guides/mailbox-import/) routes under `/emails/imports`, all with JWT permission `MANAGE_EMAILS`. They carry passwords, so like onboarding they never accept an API key:
* `POST /emails/imports/preview`: what an import of this input would do, row by row and domain by domain, without doing any of it
* `POST /emails/imports`: store the rows and connect them in the background; answers `201` with the import
* `GET /emails/imports`: the workspace's imports, newest first
* `GET /emails/imports/:id`: one import with its counts and its failures grouped by `cause`
* `GET /emails/imports/:id/rows`: an import's rows by line, filtered by `status` (comma-separated) and `cause`
* `PATCH /emails/imports/:id/rows/:line`: correct one failed row (`password`, `app_password`, `username`, `smtp`, `imap`) and queue it again
* `POST /emails/imports/:id/retry`: requeue failed rows, all of them or those with one `cause` or the listed `lines`, optionally with one new `password` for all
* `POST /emails/imports/:id/cancel`: stop the rows not yet started; rows already connecting finish
* `POST /emails/imports/:id/dismiss`: hide the import from `GET /emails/imports` for the workspace, stopping it first when it is still running. Its rows and history stay, and `GET /emails/imports/:id` still reads it. Answers `204`; a repeat changes nothing
* `GET /emails/imports/:id/failed.csv`: every row that did not connect, as uploaded minus passwords, with `status`, `problem` and `how_to_fix`
Preview and create take `multipart/form-data`: `file` (CSV, TSV or XLSX up to 10 MB) or `text` (a pasted list), `mapping` (a JSON object of column index to field, such as `{"0":"email","1":"password"}`; omit it to use the automatic mapping) and `options` (JSON: `has_header`, `shared_password`, `on_existing` of `update` or `skip`, `save_mapping`, and `settings` applied to every mailbox). One import takes up to 5,000 rows. The two lists answer `data` plus `pagination` with `next_cursor` and `has_more`; `limit` is at most `100` for imports and `200` for rows, and a cursor that is not one this API issued returns `400` with `invalid_cursor`. None of these takes an `Idempotency-Key`. Repeating a create makes a second import, whose rows find the first one's mailboxes already connected and update (or skip) them, so nothing is connected twice. A retry only requeues rows that failed, and a fix is refused for a row that is not failed, so repeating either connects nothing twice. Cancelling an import twice is a no-op. Progress is published as the realtime event `MAILBOX_IMPORT_PROGRESS`; see [realtime](/api/realtime/). Error codes are under [mailbox import refusals](/api/error-codes/#mailbox-import-refusals)
* [Inbox vendor](/guides/mailbox-import/#import-from-an-inbox-vendor) connections under `/emails/vendors`, JWT permission `MANAGE_EMAILS`. The key is sealed on the server and no response ever returns it:
* `GET /emails/vendors/catalog`: the supported vendors, with each one's `fields` (key, label, secret, required, help) and `key_help_url`
* `GET /emails/vendors`: the workspace's vendor connections with `status`, `last_error` and mailbox count
* `POST /emails/vendors`: `vendor`, `label` and `fields`; the key is checked with the vendor first, answers `201`. Repeating it makes a second connection
* `PATCH /emails/vendors/:id`: rename, or replace `fields` after checking the new key with the vendor. Safe to repeat
* `DELETE /emails/vendors/:id`: forget the key; the mailboxes it brought in stay connected. A repeat is a `404`
* `GET /emails/vendors/:id/mailboxes`: the vendor account's mailboxes, each marked `connected` when already in the workspace
* `POST /emails/vendors/:id/import`: `mailbox_ids` or `all`, plus the same `options` as a file import; answers `201` with the import. Each call creates a new import; a repeat finds the first run's mailboxes connected and updates (or skips) them
* [Admin grants](/guides/mailbox-import/#connect-a-whole-google-workspace-domain) under `/emails/grants`, JWT permission `MANAGE_EMAILS`. The four routes that record, use or remove a grant also need a [recent confirmation](#actions-that-need-a-recent-confirmation):
* `GET /emails/grants/config`: whether this instance takes Google and Microsoft grants, the Google `google_client_id` and `google_scopes` an administrator authorizes, and `google_missing` and `microsoft_missing`, the names of the instance settings still unset (empty when that provider is ready)
* `GET /emails/grants`, `GET /emails/grants/:id`: grants with their `provider`, `tenant`, covered `domains`, `status` and mailbox count
* `GET /emails/grants/migration`: the workspace's mailboxes on per-mailbox Google sign-in that can [optionally switch connection methods](/guides/mailboxes/#moving-off-per-mailbox-google-sign-in), grouped by domain: `data` is a list of `domain`, `kind` (`workspace`, which moves onto an admin grant, or `personal`, a shared address such as `gmail.com`, which moves to an app password), `grant_id` when the workspace has an active Google grant covering the domain, and `mailboxes` (`id`, `email`, `name`, `status`); `total` counts the mailboxes. Mailboxes whose sign-in AY Inbox Cloud holds are not listed. Read only
* `POST /emails/grants/google/start`: `domain` and `admin_email` (on that domain). Answers how this workspace proves it controls the domain: `method` `signin` with a Google sign-in `url` and `state` (valid for 15 minutes) when the instance has a Google sign-in app, else `method` `dns`. Both carry `txt_name` (`_ayinbox.`) and `txt_value` (`ayinbox-verify=...`, unique to the workspace and domain), because the DNS proof always works. Safe to repeat
* `POST /emails/grants/google/finish` (recent confirmation): either `state` and `code` from the Google sign-in, which must be `admin_email` itself on that domain, or `domain` and `admin_email` once the `TXT` record is published. The directory must list `admin_email` as a super administrator. Answers `201`. A `state` is single-use; repeating a DNS finish re-verifies and updates the same grant, one per domain
* `POST /emails/grants/microsoft/start`: the admin consent `url` and `state` for a Global Administrator, valid for 15 minutes
* `POST /emails/grants/microsoft/finish` (recent confirmation): `state` and `code` from the consent callback; answers `201`. The organization recorded is the one the administrator consented for, as the redeemed sign-in reports it. The `state` is single-use, so a repeat is refused with `mailbox_grant_state_invalid`. One grant per tenant: consenting again updates the same grant
* `POST /emails/grants/:id/check`: verify now, and restart the grant's stopped mailboxes when it passes. Safe to repeat
* `DELETE /emails/grants/:id` (recent confirmation): remove the grant; every mailbox it connected stops. A repeat is a `404`
* `GET /emails/grants/:id/users`: the granted directory, each user marked `enabled` and `connected`, with `email_account_id` when connected. `upgrade` is `true` for a user whose mailbox is already here on its own sign-in with the same provider (Google or Microsoft, not held by AY Inbox Cloud): connecting it moves that mailbox onto the grant in place
* `POST /emails/grants/:id/connect` (recent confirmation): `user_ids` or `all` (every enabled user not yet connected, plus every user marked `upgrade`), plus import `options`; answers `201` with the import. Each call creates a new import; a repeat finds the first run's mailboxes connected and updates (or skips) them. A user whose mailbox is already here as a delegated mailbox is relinked to this grant, and one on its own sign-in is converted onto the grant in place, keeping its history, campaigns and warmup, without counting against the mailbox allowance
* [Sending domains](/guides/sending-domains/) under `/emails/domains`, member permission `MANAGE_EMAILS`; these also take an API key, see [sending domains](#sending-domains). `:domain` is the bare domain:
* `GET /emails/domains`: every domain the workspace sends from, with mailbox count, mail hosts, SPF, DKIM and DMARC, tracking hosts in use and the redirect. When a connected [inbox vendor](/guides/sending-domains/#domains-held-by-an-inbox-vendor) account holds the domain, `vendor_domain` carries `vendor`, `connection_id`, the current `forwarding` when the vendor reports it, `can_forward`, `can_unforward`, `forwarding_reviewed` (a change is applied later by the vendor's staff), `can_dns` and `dns_types`
* `POST /emails/domains/bulk`: `domains` (1 to 100), `tracking_label` (one DNS label, such as `link`; each domain gets `