Managing Campaigns via API

Create and send campaigns programmatically

Managing Campaigns via API

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": "<h1>March Newsletter</h1><p>Content here...</p>",
  "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.

Managing Campaigns via API