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":  "[email protected]",
  "reply_to":    "[email protected]",
  "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 in draft status
400 — from_email is not a verified account
429 — Daily or monthly send limit would be exceeded
403 — Insufficient campaign ownership