Quickstart
Create an API key and make your first requests.
Create an API key
In Alienmail, open Workspace settings → Integrations and find API keys. Enter a key name (like "CRM sync"), pick the Write Access Key role so the key can add leads, and create the key.
The key is shown only once, so copy it now and keep it in your server's secrets. The examples below read it from an environment variable:
export ALIENMAIL_API_KEY="paste your key here"Use API keys only from your servers. Never put them in a web page, a mobile app or a public repository.
Make your first request
List your campaigns, newest first.
curl "https://app.alienmail.io/api/v1/campaigns?limit=5" \
-H "Authorization: Bearer $ALIENMAIL_API_KEY"You get a page of campaigns:
{
"data": [
{
"id": 42,
"name": "Q1 outreach",
"status": "active",
"leadCount": 180,
"sentCount": 412,
"lastSentAt": "2026-11-13T09:30:00.000Z",
"createdAt": "2026-11-02T08:15:00.000Z",
"updatedAt": "2026-11-13T09:30:00.000Z"
}
],
"nextCursor": null
}Note the id of the campaign you want to work with. It is also the number in the campaign's URL in Alienmail.
Add a lead to a campaign
Send people by email address. Replace 42 with your campaign id.
curl -X POST "https://app.alienmail.io/api/v1/campaigns/42/leads" \
-H "Authorization: Bearer $ALIENMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"leads": [
{
"email": "ada@example.com",
"firstName": "Ada",
"lastName": "Lovelace",
"company": "Analytical Engines",
"custom": { "plan": "pro" }
}
]
}'The answer says what happened to each person:
{
"received": 1,
"added": 1,
"reactivated": 0,
"alreadyIn": 0,
"skippedBounced": 0,
"skippedUnsubscribed": 0,
"invalid": [],
"ignoredCustomKeys": []
}Calling it again with the same person is safe: they are counted in alreadyIn and not added twice. See Sync leads for the full rules.
Stop emailing someone
When a lead becomes a customer, stop their emails. The lead is addressed by email, with @ written as %40.
curl -X PATCH "https://app.alienmail.io/api/v1/campaigns/42/leads/ada%40example.com" \
-H "Authorization: Bearer $ALIENMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "stopped" }'Try any endpoint in the browser
Every page of the API reference has a playground. Paste your key in Authorization, fill in the fields and press Send to see the real response.
The playground calls the live API with your key, so writes are real. Use a test campaign while you explore.