Campaigns and mailboxes
List, start and pause campaigns, and manage the mailboxes they send from.
Campaigns
List campaigns returns your workspace's campaigns, newest first, with a count of leads and of emails sent.
curl "https://app.alienmail.io/api/v1/campaigns?status=active" \
-H "Authorization: Bearer $ALIENMAIL_API_KEY"| Status | Meaning |
|---|---|
draft | Not started yet. |
active | Sending. |
paused | Stopped by you. Nothing is sent until it is started again. |
completed | Finished its sequence, or reached its end date. |
archived | Put away in Alienmail. Read-only through the API. |
Campaigns are created, written and scheduled in Alienmail. The API starts and pauses them.
Start or resume
curl -X POST "https://app.alienmail.io/api/v1/campaigns/42/start" \
-H "Authorization: Bearer $ALIENMAIL_API_KEY"Start a campaign works on a draft, paused or completed campaign and returns it with status active. Leads that were pending become active, and each lead's next email is queued: the first email for new leads, the next follow-up for leads part-way through. Waits between steps count from when the last email was sent, so a pause doesn't restart them.
A start is refused with 409 when:
- the campaign is
archived; - its end date has passed;
- none of its email steps has content;
- no mailbox attached to it is active and connected.
message says which. Starting a campaign that is already active returns it unchanged.
Pause
curl -X POST "https://app.alienmail.io/api/v1/campaigns/42/pause" \
-H "Authorization: Bearer $ALIENMAIL_API_KEY"Pause a campaign stops sending and takes the waiting emails off the queue. Only an active campaign can be paused; a paused one is returned unchanged, and any other status returns 409.
An email that is being sent at the moment you pause may still go out.
Mailboxes
List mailboxes returns the mailboxes connected to your workspace. It never returns passwords, tokens or server settings.
curl "https://app.alienmail.io/api/v1/mailboxes" \
-H "Authorization: Bearer $ALIENMAIL_API_KEY"{
"data": [
{
"id": 7,
"email": "ada@analyticalengines.com",
"name": "Ada from Analytical Engines",
"provider": "google",
"active": true,
"connected": true,
"rateLimited": false,
"dailyLimit": 50,
"sentToday": 12,
"createdAt": "2026-10-01T10:00:00.000Z",
"updatedAt": "2026-11-13T09:30:00.000Z"
}
],
"nextCursor": null
}| Field | Meaning |
|---|---|
active | Whether campaigns may send from the mailbox. You set it. |
connected | false when the last connection check failed. Reconnect the mailbox in Alienmail. |
rateLimited | The mail provider is throttling the mailbox. |
dailyLimit, sentToday | The most emails it sends per day, and how many count against that today. |
Campaigns send only from mailboxes that are both active and connected. A simple health check is to list mailboxes and alert on any with connected: false.
Update a mailbox
Update a mailbox changes the sender name, the daily limit (1 to 2,000) or the on/off switch. Only what you send changes.
curl -X PATCH "https://app.alienmail.io/api/v1/mailboxes/7" \
-H "Authorization: Bearer $ALIENMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "dailyLimit": 30, "active": true }'Mailboxes are connected, reconnected and deleted in Alienmail. Server settings, logins and passwords can't be read or changed through the API.