Campaigns are bulk email sends to a segment of your contacts. Campaigns support scheduling, tracking, and analytics.

Auth: API key with campaigns scope.

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

List campaigns

GET/mail/v1/campaigns

List campaigns with optional status filter.

Query parameters

statusstringquery

Filter: draft, scheduled, sending, sent, failed.

pagenumberquerydefault: 1

Page number.

per_pagenumberquerydefault: 20

Per page (max 50).

Response fields

successboolean

true when the request succeeded.

campaignsArray<Campaign>

The page of campaigns. Each includes id, name, subject, status, segment_id, total_recipients, total_sent, total_opened, total_clicked, total_bounced, sent_at, and created_at.

paginationobject

Pagination metadata: page, per_page, total.

{
  "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 }
}

Create a campaign

POST/mail/v1/campaigns

Create a new campaign. Plan limits apply.

Request body

namestringbodyrequired

Internal name.

subjectstringbodyrequired

Email subject line (supports {{variables}}).

from_namestringbody

Sender display name.

from_emailstringbodyrequired

Must be a verified account.

reply_tostringbody

Reply-to address.

segment_idstringbodyrequired

Target audience segment.

template_idstringbody

Use a template instead of inline HTML. Provide template_id or body_html (one required).

body_htmlstringbody

Inline HTML body. Provide template_id or body_html (one required).

body_textstringbody

Plain text fallback (recommended).

Response fields

successboolean

true when the campaign was created.

campaignobject

The created campaign, including id, name, and status.

{
  "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}}!"
}

{
  "success": true,
  "campaign": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "February Newsletter",
    "status": "draft"
  }
}

Errors

403 — Campaign limit reached for your plan

Update a campaign

PATCH/mail/v1/campaigns/:id

Update a draft campaign. Cannot update campaigns that are sending or sent. Any subset of campaign fields may be sent.

Path parameters

idstringpathrequired

ID of the campaign to update.

Request body

subjectstringbody

Updated subject line.

body_htmlstringbody

Updated HTML content.

{
  "subject": "Updated subject line",
  "body_html": "<h1>Updated content</h1>"
}

Delete a campaign

DELETE/mail/v1/campaigns/:id

Delete a draft campaign. Cannot delete scheduled, sending, or sent campaigns.

Path parameters

idstringpathrequired

ID of the draft campaign to delete.

curl -X DELETE https://api.misar.io/mail/v1/campaigns/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer msk_your_key"

Send or schedule a campaign

POST/mail/v1/campaigns/:id/send

Send or schedule a campaign. The campaign must be in draft status. Omit send_at to send immediately.

Path parameters

idstringpathrequired

ID of the draft campaign.

Request body

send_atstringbody

ISO-8601 time to schedule the send. Omit to send immediately.

Response fields

successboolean

true when the send was accepted.

campaign_idstring

ID of the campaign.

statusstring

Resulting status, e.g. sending.

scheduled_atstring

Scheduled send time, or null for immediate sends.

estimated_recipientsnumber

Estimated number of recipients.

{
  "send_at": "2026-03-01T10:00:00Z"
}

{
  "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

Campaign Sub-Endpoints

These endpoints operate on an existing campaign by ID.

Get campaign sends

GET/mail/v1/campaigns/:id/sends

Get per-recipient send records for a campaign with status tracking.

Auth: API key with campaigns scope.

Path parameters

idstringpathrequired

ID of the campaign.

Query parameters

pagenumberquerydefault: 1

Page number.

limitnumberquerydefault: 50

Results per page (max 100).

statusstringquery

Filter: sent, delivered, opened, clicked, bounced, complained, unsubscribed, failed.

Response fields

successboolean

true when the request succeeded.

campaignobject

Summary: id, name, status, total_sent, total_failed.

breakdownobject

Aggregate counts: sent, bounced, opened, clicked, failed.

dataArray<Send>

Per-recipient send records, each with id, email, contact_id, status, sent_at, opened_at, clicked_at, bounced_at, and error_message.

paginationobject

Pagination metadata: page, limit, total, totalPages.

{
  "success": true,
  "campaign": { "id": "...", "name": "Spring Sale", "status": "sent", "total_sent": 5200, "total_failed": 3 },
  "breakdown": { "sent": 5197, "bounced": 48, "opened": 2038, "clicked": 510, "failed": 3 },
  "data": [
    {
      "id": "send_...",
      "email": "[email protected]",
      "contact_id": "...",
      "status": "opened",
      "sent_at": "2026-04-01T09:01:00Z",
      "opened_at": "2026-04-01T09:15:00Z",
      "clicked_at": null,
      "bounced_at": null,
      "error_message": null
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 5200, "totalPages": 104 }
}

Create an A/B test variant

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

Create an A/B test variant for a campaign.

Auth: API key with campaigns scope. Plan: Pro+.

Path parameters

idstringpathrequired

ID of the campaign.

Request body

variantstringbodyrequired

Label e.g. "B", "C".

test_typestringbodydefault: content

content, subject, send_time, from_name, preheader.

subjectstringbody

Variant subject (for test_type: subject).

preheaderstringbody

Variant preheader (for test_type: preheader).

body_htmlstringbody

Variant HTML (for test_type: content).

from_namestringbody

Variant sender name.

send_percentnumberbodydefault: 50

% of audience for this variant (1-99).

auto_select_winnerbooleanbody

Auto-select winner after wait.

winner_wait_hoursnumberbodydefault: 4

Hours to wait (1-168).

curl -X POST https://api.misar.io/mail/v1/campaigns/camp_abc123/ab-tests \
  -H "Authorization: Bearer msk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "variant": "B",
    "test_type": "subject",
    "subject": "Don'\''t miss our Spring Sale 🌸",
    "send_percent": 50,
    "auto_select_winner": true,
    "winner_wait_hours": 4
  }'

Optimize send time

POST/mail/v1/campaigns/:id/optimize

AI-powered send time optimization. Analyzes past open patterns to recommend the best send window. Calling this endpoint also updates the campaign's scheduled_at to the recommended time.

Auth: API key with campaigns scope. Plan: Pro+.

Path parameters

idstringpathrequired

ID of the campaign.

Response fields

successboolean

true when the request succeeded.

recommendationobject

Recommended window: day_of_week, hour_utc, confidence, basis.

scheduledAtstring

ISO-8601 time the campaign was scheduled to.

{
  "success": true,
  "recommendation": {
    "day_of_week": "Tuesday",
    "hour_utc": 9,
    "confidence": 0.87,
    "basis": "Your subscribers have 40% higher open rates on Tuesday 9-10am UTC"
  },
  "scheduledAt": "2026-06-03T09:00:00Z"
}

Predict campaign performance

POST/mail/v1/campaigns/:id/predict

Predict expected open and click rates before sending based on subject line and segment characteristics.

Auth: API key. Plan: Pro+.

Path parameters

idstringpathrequired

ID of the campaign.

Response fields

successboolean

true when the request succeeded.

predictionsobject

Predicted metrics: expectedOpenRate, expectedClickRate, confidence, factors.

{
  "success": true,
  "predictions": {
    "expectedOpenRate": 0.34,
    "expectedClickRate": 0.08,
    "confidence": 0.72,
    "factors": ["subject_length_optimal", "good_send_time", "segment_recently_engaged"]
  }
}

Rewrite campaign content

POST/mail/v1/campaigns/:id/rewrite

AI-rewrite the campaign content with spam-word filtering and deliverability checks. Updates the campaign body in-place.

Auth: API key. Plan: Pro+.

Path parameters

idstringpathrequired

ID of the campaign.

Request body

instructionsstringbody

Rewrite instructions.

tonestringbody

Desired tone, e.g. friendly.

Response fields

successboolean

true when the rewrite succeeded.

dataobject

Rewritten content: subject, html, preheader.

{
  "instructions": "Make it more conversational and reduce the subject line length",
  "tone": "friendly"
}

{
  "success": true,
  "data": {
    "subject": "Spring is here — don't miss it",
    "html": "<p>...</p>",
    "preheader": "Your exclusive spring offer inside"
  }
}

Save as template

POST/mail/v1/campaigns/:id/save-as-template

Save a campaign as a reusable template.

Auth: API key.

Path parameters

idstringpathrequired

ID of the campaign.

Request body

namestringbody

Template name.

descriptionstringbody

Template description.

Response fields

successboolean

true when the template was created.

templateobject

The created template: id, name, created_at.

{
  "name": "Spring Sale Template",
  "description": "Seasonal sale email format"
}

{
  "success": true,
  "template": {
    "id": "tpl_abc123",
    "name": "Spring Sale Template",
    "created_at": "2026-05-27T10:00:00Z"
  }
}

Configure reply webhook

POST/mail/v1/campaigns/:id/reply-webhook

Configure a webhook URL to receive replies to this campaign (inbound replies forwarded in real time). Replies are POSTed to your URL with payload: { "campaign_id", "from_email", "from_name", "subject", "text", "html", "received_at" }.

Auth: API key.

Path parameters

idstringpathrequired

ID of the campaign.

Request body

webhook_urlstringbody

URL to receive inbound replies.

secretstringbody

Signing secret for verifying webhook payloads.

{
  "webhook_url": "https://yourapp.com/webhooks/replies",
  "secret": "whsec_..."
}