Authentication
Every request to the Warmerly API is authenticated with an API key, sent as the
X-Api-Key header.
Getting a key
- Sign in to app.warmerly.com.
- Go to Settings → API Keys.
- Click Create key, name it, and copy the secret shown — it is only displayed once and cannot be retrieved again. If you lose it, revoke the key and create a new one.
Keys are prefixed wmv_ and are scoped to your user account (they can access every
workspace/project you're a member of, subject to the project you select via
X-Project-Id).
Required headers
| Header | Required | Description |
|---|---|---|
X-Api-Key | Always | Your API key secret. |
X-Project-Id | Most endpoints | The UUID of the project to operate on (mailboxes, campaigns, and inbox data all belong to a project). Find it in the dashboard URL or via the Workspaces & Projects endpoints. |
curl https://app.warmerly.com/api/v1/accounts \
-H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-Project-Id: 8f14e45f-ceea-4c6a-8c8d-6b1a5b5c9c1a"
Endpoints that aren't project-scoped (e.g. listing your workspaces, managing API
keys) only need X-Api-Key.
Rate limits
Each key has its own per-minute rate limit (default 60 requests/minute, configurable
per key up to 120). Exceeding it returns 429 too_many_requests. A few endpoints layer
an additional, tighter limit on top of this. See Errors & Rate Limits for the
full picture, including the exact response shape and per-endpoint limits.
Revoking a key
Revoke a key any time from Settings → API Keys. Revoked keys fail every request
immediately with 401 unauthorized — there is no grace period.
Errors
An invalid or revoked key returns 401:
{ "error": { "code": "unauthorized", "message": "unauthorized", "details": null } }
A missing or malformed X-Project-Id on a project-scoped endpoint returns 400:
{ "error": { "code": "bad_request", "message": "missing X-Project-Id header", "details": null } }