API overview

The AY Inbox API lets you drive everything you can do in the dashboard programmatically: mailboxes, campaigns, contacts, the unibox, and more. It is a JSON API over HTTPS.

https://api.ayinbox.com/v1

Quickstart

Create an API key in your dashboard under Settings, then pass it as a Bearer token on every request:

curl -X GET "https://api.ayinbox.com/v1/campaigns" \
  -H "Authorization: Bearer aybox_your_api_key_here" \
  -H "Content-Type: application/json"

See Authentication for the key format, scoping, and security guidance. Connecting an AI agent instead? Start with the agent quickstart.

Versioning

The API is versioned in the URL. The current version is v1, and the base URL includes it: every endpoint path in these docs is relative to https://api.ayinbox.com/v1.

• Stability: within a version, changes are additive (new fields, new endpoints). A breaking change ships as a new version, so code written against v1 keeps working.
• Version header: every response carries an API-Version header so you can confirm which version answered.
• No unversioned alias: every endpoint lives under /v1; there are no bare, unversioned paths. A future breaking change will ship as /v2 while /v1 keeps working.

Conventions

• Permissions: every key carries an explicit permission set; a request beyond the key's permissions returns 403. The full list is in the permissions reference.
• List responses: list endpoints return a consistent data plus pagination shape with opaque cursors.
• Errors: error responses carry a machine-readable code and a request_id alongside the human-readable text. Client logic should branch on code and HTTP status, never on message text. See error codes.
• Endpoint coverage: the endpoint scope map lists every route, whether it accepts API keys, and which permission it requires. The endpoint reference documents each route's request and response structures, grouped by resource.

{
  "data": [],
  "pagination": { "has_more": false, "next_cursor": null }
}

Client libraries

There are no official client libraries yet. Any HTTP client works against the API directly, and a typed client can be generated from the OpenAPI document. See SDKs.