# Managing Campaigns via API

Create and send campaigns programmatically

The Campaigns API allows you to create, configure, and send email campaigns programmatically. This is useful for automated campaign creation from your CMS, scheduled batch sends from external systems, or building custom campaign management interfaces.

## Create a campaign

```
POST /api/v1/campaigns

{
  "name": "March Newsletter",
  "subject": "What's new this month",
  "preheader": "Product updates, tips, and more",
  "from_name": "Acme Team",
  "from_email": "news@yourdomain.com",
  "reply_to": "hello@yourdomain.com",
  "html_content": "

# March Newsletter

Content here...

",
  "text_content": "March Newsletter

Content here...",
  "segment_ids": [5, 12],
  "exclude_segment_ids": [8]
}
```

## Request fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Internal campaign name |
| `subject` | string | Yes | Email subject line |
| `preheader` | string | No | Preview text shown in inbox |
| `from_name` | string | Yes | Sender display name |
| `from_email` | string | Yes | Sender email (must be on a verified domain) |
| `reply_to` | string | No | Reply-to address |
| `html_content` | string | Yes | Full HTML body of the email |
| `text_content` | string | No | Plain text version |
| `segment_ids` | array | Yes | Target audience segments |
| `exclude_segment_ids` | array | No | Segments to exclude from the send |

The campaign is created in **draft** status. It will not send until you explicitly trigger it.

## Get campaign details

```
GET /api/v1/campaigns/:id
```

Returns the full campaign record including status, content, target segments, exclusion segments, analytics (if sent), and timestamps.

## Update a draft campaign

```
PUT /api/v1/campaigns/:id

{
  "subject": "Updated: What's new this month",
  "preheader": "Fresh content inside"
}
```

Only draft campaigns can be updated. Campaigns that are scheduled, sending, or sent cannot be modified.

## Send a campaign

```
POST /api/v1/campaigns/:id/send
```

Triggers the campaign to begin sending immediately. Before sending, Mailnaptic validates:

- The from email is on a verified domain with valid DNS records.
- The organization has a mailing address set (CAN-SPAM compliance).
- At least one target segment is specified.
- The campaign has HTML content.

If validation fails, the response includes specific error messages.

## Schedule a campaign

```
POST /api/v1/campaigns/:id/schedule

{
  "send_at": "2026-03-25T09:00:00Z"
}
```

Schedules the campaign for a future date and time. The `send_at` value must be in ISO 8601 format and at least 5 minutes in the future. To cancel a scheduled campaign, update its status back to draft.

## List campaigns

```
GET /api/v1/campaigns?status=sent&page=1&per_page=20
```

Filter by status: `draft`, `scheduled`, `sending`, `sent`, `paused`.

## Campaign analytics

```
GET /api/v1/campaigns/:id/analytics
```

Returns detailed analytics for a sent campaign:

```
{
  "data": {
    "recipients": 5000,
    "delivered": 4920,
    "opened": 1845,
    "clicked": 623,
    "bounced": 80,
    "complained": 3,
    "unsubscribed": 12,
    "open_rate": 0.375,
    "click_rate": 0.127
  }
}
```

## Compliance checks

The send endpoint enforces the same compliance rules as the UI:

- Campaigns require a mailing address in your organization settings.
- Exclusion segments are applied before queuing recipients.
- Frequency caps are respected if configured for your organization.
- Contacts who have unsubscribed or complained are automatically excluded.

> **Scope required:** `campaigns:write` for creating, updating, and sending. `campaigns:read` for listing and analytics.
