API overview

The Warmbly 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.warmbly.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.warmbly.com/v1/campaigns" \
  -H "Authorization: Bearer wmbly_your_api_key_here" \
  -H "Content-Type: application/json"

See Authentication for the key format, scoping, and security guidance.

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.warmbly.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. Official libraries (Node.js, Python, Go) will get their own sections in these docs when they ship.