Campaigns

Base: https://api.misar.io/mail/v1/campaigns

Required scope: write (mutating) / read (read-only)

List campaigns

GET /v1/campaigns

Query params: status (draft|scheduled|sending|sent|paused), page, limit.

{
  "success": true,
  "data": [
    {
      "id": "camp_01ABCDEF",
      "name": "June Newsletter",
      "status": "draft",
      "subject": "What's new in June",
      "scheduledAt": null,
      "createdAt": "2025-06-01T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 12 }
}

Get campaign

GET /v1/campaigns/:id

Returns full campaign object including stats when status=sent.

Create campaign

POST /v1/campaigns

{
  "name": "June Newsletter",
  "subject": "What's new in June",
  "fromEmail": "[email protected]",
  "fromName": "Your Brand",
  "html": "<p>This month we shipped...</p>",
  "segmentId": "seg_01ABCDEF",
  "scheduledAt": "2025-06-15T09:00:00Z"
}

Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | ✅ | Internal campaign name | | subject | string | ✅ | Email subject | | fromEmail | string | ✅ | Verified sender address | | fromName | string | — | Sender display name | | html | string | ✅* | HTML body (or templateId) | | templateId | string | ✅ | Saved template ID | | segmentId | string | — | Target segment (null = all contacts) | | scheduledAt | string | — | ISO 8601; omit to save as draft | | replyTo | string | — | Reply-to email | | preheader | string | — | Preview text in inbox |

Update campaign

PATCH /v1/campaigns/:id

Accepts any subset of the create fields. Only draft campaigns can be updated.

Delete campaign

DELETE /v1/campaigns/:id

Only draft or cancelled campaigns can be deleted.

Send / schedule campaign

POST /v1/campaigns/:id/send

{
  "scheduledAt": "2025-06-15T09:00:00Z"
}

Omit scheduledAt to send immediately. Returns:

{
  "success": true,
  "status": "sending",
  "estimatedRecipients": 4821
}

A/B test

Create variant

POST /v1/campaigns/:id/ab-tests

{
  "subject": "Alternative subject line",
  "splitPercent": 20
}

splitPercent — percentage of audience receiving this variant (remaining goes to the original). Max 50 per side.

Declare winner

POST /v1/ab-tests/:id/winner

{
  "variantId": "abt_01ABCDEF",
  "sendRemainder": true
}

Set sendRemainder: true to immediately send the winning variant to the remaining audience.

AI rewrite

POST /v1/campaigns/:id/rewrite

{
  "tone": "friendly",
  "goal": "increase clicks"
}

Returns a new html body. Does not auto-save — apply by PATCHing the campaign.

Campaign stats (after send)

{
  "sent": 4821,
  "delivered": 4789,
  "opened": 1923,
  "clicked": 412,
  "bounced": 32,
  "unsubscribed": 8,
  "openRate": 0.402,
  "clickRate": 0.086
}