The warmbly CLI
Sign in once through the browser, then run campaigns, contacts and the inbox from your terminal or CI. It prints a table to a person and JSON to a pipe, and asks before anything sends real mail.
brew install warmbly/tap/warmblyDevelopers
Everything in the dashboard is an API call.
Add contacts, launch campaigns, read replies and react to events from your own code. Scoped keys, safe retries and signed webhooks come as standard, and the whole thing is open source.
curl -X POST "https://api.warmbly.com/v1/contacts" \
-H "Authorization: Bearer $WARMBLY_API_KEY" \
-H "Idempotency-Key: 7f3c9a2e-import-01" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"first_name": "Dana",
"company": "Acme",
"campaigns": ["4c1d7a90-2f3b-4e8a-9d61-0b5e7f2c3a18"]
}'Response201 Created
[
{
"id": "2c3d4e5f-6071-4b2c-9d3e-4f5a6b7c8d9e",
"email": "[email protected]",
"first_name": "Dana",
"company": "Acme",
"subscribed": true,
"campaigns": [{ "id": "4c1d7a90-…", "name": "Q3 outbound" }]
}
]Five ways in. Pick the one that fits the job.
The REST API is underneath all of them. The CLI and the SDKs wrap it, the MCP server hands it to an AI client, and the realtime stream pushes its events to you as they happen.
An MCP server for AI clients
Give Claude, Cursor or any MCP client your contacts, campaigns and inbox as tools. It signs in with OAuth, sees only the scopes your role allows, and drafts replies rather than sending them.
claude mcp add --transport http warmbly https://api.warmbly.com/v1/mcpJavaScript and TypeScript
$ npm install warmbly
new Warmbly({ apiKey: "wmbly_..." }); // API key
new Warmbly({ accessToken: "wmat_..." }); // OAuth tokenNode 20+, Bun, Deno, browsers, edge · typed, auto-paginating, retries built in
Python
$ pip install warmbly
client = Warmbly() # reads WARMBLY_API_KEY
for key in client.api_keys.list():
print(key.name, key.status)Python 3.10+, sync and async · typed, auto-paginating, retries built in
Go
$ go get github.com/warmbly/warmbly-go
client, err := warmbly.New(
warmbly.WithAPIKey("wmbly_..."),
)Go 1.23+ · typed, auto-paginating, retries built in
Webhooks. Every event, signed and logged.
Subscribe an HTTPS endpoint to replies, sends, bounces, new contacts, booked meetings and more. Each delivery is signed with your endpoint’s secret, and every attempt is kept so you can see what your server answered.
- Signed
- An HMAC-SHA256 signature over the timestamp and the raw body, with your endpoint’s secret.
- Retried
- Up to 8 attempts with backoff from 30 seconds to an hour, then marked abandoned.
- Replayable
- Every attempt is in the delivery log, and a failed one can be sent again with its original event id.
- HTTPS only
- Private, loopback and link-local addresses are refused, and redirects are never followed.
Realtime. The stream the dashboard runs on.
Open one WebSocket with a key that has REALTIME_SUBSCRIBE and receive sends, opens, replies, audit entries and your own custom events as they happen, filtered by the same permissions as the dashboard.
Read the realtime guide
In order
Every event carries a sequence number, so you always know what came first.
Resumable
Reconnect with the last sequence you handled and the events you missed are replayed.
Narrowed by intent
Join with the event families you act on and the rest never reach you.
Built to be relied on. Retries, permissions and errors you can plan around.
Safe retries
Send an Idempotency-Key with any write. A retry within 24 hours gets the original response back instead of doing the work twice.
Scoped keys
A key can read and write contacts without being able to send a single email. Give each integration only what it needs, and limit it to your own IP addresses.
Errors with a code
Every error carries a stable code for your logic and a request id for support, next to a message written for people.
Questions. The API, answered.
How do I authenticate?
Create an API key under Settings and send it as a Bearer token on every request. Each key carries only the scopes you give it, and can be limited to certain IP addresses. Apps acting for other people use OAuth instead.
Are retries safe?
Yes. Send an Idempotency-Key header with any write, and Warmbly stores the response for 24 hours and replays it for a retry with the same key instead of doing the work twice.
How do I verify a webhook?
Every delivery carries an X-Warmbly-Signature header of the form t=<timestamp>,v1=<signature>. Compute an HMAC-SHA256 of the timestamp, a dot and the raw body with your endpoint’s secret, and compare. Webhook targets must be HTTPS.
What do errors look like?
Every error has a stable machine-readable code and a request_id, next to a human-readable message. Build your logic on the code and the HTTP status, and quote the request_id when you contact us.
Can an AI assistant send email through the MCP server?
No. Over MCP the assistant can read, organise and draft, but tools that send a message to a recipient are never exposed, and a client that signs in over OAuth is never given the scope that starts campaigns.
Is there an API for self-hosted instances?
The same one. A self-hosted instance serves the same API on its own domain, and the SDKs and CLI can point at any host.
Build on Warmbly.
Create an API key, send your first request, and get every event back as a signed webhook.