---
title: API overview
description: Base URL, conventions, and a quickstart for the Warmbly API.
---

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:

```bash
curl -X GET "https://api.warmbly.com/v1/campaigns" \
  -H "Authorization: Bearer wmbly_your_api_key_here" \
  -H "Content-Type: application/json"
```

See [Authentication](/api/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](/api/permissions/).
- **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](/api/error-codes/).
- **Endpoint coverage**: the [endpoint scope map](/api/endpoints/) lists every route, whether it accepts API keys, and which permission it requires. The [endpoint reference](/api/reference/mailboxes/) documents each route's request and response structures, grouped by resource.

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

## Client libraries

Warmbly publishes official, typed SDKs for JavaScript and TypeScript, Python, and Go. They wrap the REST API, the OAuth2 flows, and the realtime gateway, with auto-pagination, retries, and typed errors built in. Any HTTP client also works against the API directly.

See [SDKs](/api/sdks/) for install commands and quickstarts.
