# How do I use Warmerly with an API?

> Create a key under Settings > Platform API keys (Agency plan or its 7-day trial), send it as X-Api-Key, and call https://app.warmerly.com/api/v1.

Source: https://warmerly.com/docs/help/use-the-api

Create an API key in **Settings > Platform API keys**, then send it in an `X-Api-Key` header to `https://app.warmerly.com/api/v1`. API access comes with the **Agency** plan, and a free trial of the Agency plan includes it too, so you can test your integration before paying.

Everything the API does is also available in the dashboard. You only need a key when you want your own code, scripts or tools like Zapier to work with Warmerly.

## Which plans include the API?

| Plan | API access |
| --- | --- |
| Free | No |
| Starter | No |
| Growth | No |
| Agency | Yes |
| Agency free trial | Yes |

On any other plan, the **Platform API keys** page shows "API access is an Agency plan feature" with an **Upgrade to Agency** button, and API calls answer `403 agency_plan_required`. See [Plans and limits](https://warmerly.com/docs/plans-and-limits) for everything else each plan includes.

## Steps

1. Sign in to [app.warmerly.com](https://app.warmerly.com/login) and open **Settings > Platform API keys**.
2. Under **Create a key**, type a name you will recognise later (for example "Production server" or "Zapier") and click **Create key**.
3. Copy the key straight away. It starts with `wmv_` and is shown only once. If you lose it, revoke it and create a new one.
4. Make your first request. Listing your keys needs nothing but the key itself:

```bash curl https://app.warmerly.com/api/v1/keys \ -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ```

A working key returns `{ "keys": [ ... ] }` with the key you just made in the list.

1. Find your project ID. Mailboxes, campaigns and inbox data belong to a project, so most endpoints also need an `X-Project-Id` header. Get the ID from [`GET /workspaces` and `GET /projects`](https://warmerly.com/docs/workspaces), or from the dashboard URL.
2. Call a project endpoint, for example your mailboxes:

```bash curl https://app.warmerly.com/api/v1/accounts \ -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "X-Project-Id: YOUR_PROJECT_ID" ```

From there, the [API reference](https://warmerly.com/docs) covers [campaigns](https://warmerly.com/docs/campaigns), [leads](https://warmerly.com/docs/leads), [verification](https://warmerly.com/docs/verify), [inbox](https://warmerly.com/docs/inbox) and [webhooks](https://warmerly.com/docs/webhooks).

## Prefer an AI assistant to writing code?

Warmerly also has an MCP server, so ChatGPT, Claude and other assistants can work with your account directly. See [Use with AI (MCP)](https://warmerly.com/docs/ai).

## Common problems

**`401 unauthorized`.** The key is wrong, has a typo, or was revoked. Revoked keys stop working immediately. Create a new key and try again.

**`403 agency_plan_required`.** The workspace is not on Agency (or an Agency trial). If you just upgraded, allow about a minute for it to take effect. Keys are not deleted when a plan changes, so they work again once the workspace is back on Agency.

**`400` "missing X-Project-Id header".** The endpoint is project-scoped. Add the `X-Project-Id` header. [Authentication](https://warmerly.com/docs/authentication) explains which endpoints need it.

**`429 too_many_requests`.** Each key has its own per-minute rate limit (60 requests a minute by default). Slow down and retry. Limits for each endpoint are in [Errors and rate limits](https://warmerly.com/docs/errors).

## Related

- [Authentication](https://warmerly.com/docs/authentication): headers, scopes and rate limits in detail
- [API keys](https://warmerly.com/docs/keys): create, list and revoke keys over the API
- [Plans and limits](https://warmerly.com/docs/plans-and-limits): what Agency includes

## More in Help centre

- [All help articles](https://warmerly.com/docs/help): Answers to common Warmerly questions: using the API, launching a campaign, importing leads, reconnecting a…
- [Launch your first campaign](https://warmerly.com/docs/help/launch-first-campaign): Go to Campaigns > New campaign, name it and add leads, write your sequence, pick your mailboxes and…
- [Import leads from a CSV](https://warmerly.com/docs/help/import-leads-csv): Open a campaign's Audience tab, click Import leads, drop in your CSV, match the Email column (plus any…