# Campaigns and mailboxes (/guides/campaigns-and-mailboxes)

## Campaigns [#campaigns]

[List campaigns](/api-reference/campaigns/listCampaigns) returns your workspace's campaigns, newest first, with a count of leads and of emails sent.

```bash
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 [#start-or-resume]

```bash
curl -X POST "https://app.alienmail.io/api/v1/campaigns/42/start" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY"
```

[Start a campaign](/api-reference/campaigns/startCampaign) 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 [#pause]

```bash
curl -X POST "https://app.alienmail.io/api/v1/campaigns/42/pause" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY"
```

[Pause a campaign](/api-reference/campaigns/pauseCampaign) 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`.

<Callout type="info">
An email that is being sent at the moment you pause may still go out.
</Callout>

## Mailboxes [#mailboxes]

[List mailboxes](/api-reference/mailboxes/listMailboxes) returns the mailboxes connected to your workspace. It never returns passwords, tokens or server settings.

```bash
curl "https://app.alienmail.io/api/v1/mailboxes" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY"
```

```json
{
  "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]

[Update a mailbox](/api-reference/mailboxes/updateMailbox) changes the sender name, the daily limit (1 to 2,000) or the on/off switch. Only what you send changes.

```bash
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.