API Reference
Campaigns
Create, manage, and send email marketing campaigns
Campaigns
Campaigns are bulk email sends to a segment of your contacts. Campaigns support scheduling, tracking, and analytics.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v1/campaigns | List campaigns |
POST | /api/v1/campaigns | Create a campaign |
GET | /api/v1/campaigns/:id | Get a campaign |
PATCH | /api/v1/campaigns/:id | Update a campaign |
DELETE | /api/v1/campaigns/:id | Delete a draft campaign |
POST | /api/v1/campaigns/:id/send | Send or schedule a campaign |
Auth: API key with campaigns scope.
GET /api/v1/campaigns
List campaigns with optional status filter.
Query Parameters
| Param | Default | Description |
|---|---|---|
status | — | Filter: draft, scheduled, sending, sent, failed |
page | 1 | Page number |
per_page | 20 | Per page (max 50) |
Response
{
"success": true,
"campaigns": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "February Newsletter",
"subject": "What's new this month",
"status": "sent",
"segment_id": "...",
"total_recipients": 5000,
"total_sent": 5000,
"total_opened": 1250,
"total_clicked": 340,
"total_bounced": 12,
"sent_at": "2026-02-01T10:00:00Z",
"created_at": "2026-01-28T09:00:00Z"
}
],
"pagination": { "page": 1, "per_page": 20, "total": 8 }
}POST /api/v1/campaigns
Create a new campaign. Plan limits apply.
Request Body
{
"name": "February Newsletter",
"subject": "What's new this month 🚀",
"from_name": "Misar Team",
"from_email": "newsletter@yourdomain.com",
"reply_to": "support@yourdomain.com",
"segment_id": "550e8400-e29b-41d4-a716-446655440001",
"template_id": "550e8400-e29b-41d4-a716-446655440002",
"body_html": "<h1>Hello {{first_name}}!</h1>",
"body_text": "Hello {{first_name}}!"
}| Field | Required | Notes |
|---|---|---|
name | ✓ | Internal name |
subject | ✓ | Email subject line (supports {{variables}}) |
from_email | ✓ | Must be a verified account |
segment_id | ✓ | Target audience segment |
template_id OR body_html | ✓ (one) | Use template or inline HTML |
body_text | — | Plain text fallback (recommended) |
Response
{
"success": true,
"campaign": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "February Newsletter",
"status": "draft"
}
}Errors
403— Campaign limit reached for your plan
PATCH /api/v1/campaigns/:id
Update a draft campaign. Cannot update campaigns that are sending or sent.
Request Body
Any subset of campaign fields:
{
"subject": "Updated subject line",
"body_html": "<h1>Updated content</h1>"
}DELETE /api/v1/campaigns/:id
Delete a draft campaign. Cannot delete scheduled, sending, or sent campaigns.
POST /api/v1/campaigns/:id/send
Send or schedule a campaign. The campaign must be in draft status.
Request Body
{
"send_at": "2026-03-01T10:00:00Z"
}Omit send_at to send immediately.
Response
{
"success": true,
"campaign_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "sending",
"scheduled_at": null,
"estimated_recipients": 5000
}Errors
400— Campaign is not indraftstatus400—from_emailis not a verified account429— Daily or monthly send limit would be exceeded403— Insufficient campaign ownership