Skip to Content
Alienmail Docs

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"
StatusMeaning
draftNot started yet.
activeSending.
pausedStopped by you. Nothing is sent until it is started again.
completedFinished its sequence, or reached its end date.
archivedPut 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
}
FieldMeaning
activeWhether campaigns may send from the mailbox. You set it.
connectedfalse when the last connection check failed. Reconnect the mailbox in Alienmail.
rateLimitedThe mail provider is throttling the mailbox.
dailyLimit, sentTodayThe 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.

On this page