MisarMisar Docs
MisarMailMisarBlogMisarReachMisarPostMisarDevMisarCoderMisarSEOMisar PlatformMisar SSO
API Reference

Campaigns

Create, manage, and send email marketing campaigns

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

Auth: API key with campaigns scope.

Endpoints

MethodPathDescription
GET/api/v1/campaignsList campaigns
POST/api/v1/campaignsCreate a campaign
GET/api/v1/campaigns/:idGet a campaign
PATCH/api/v1/campaigns/:idUpdate a campaign
DELETE/api/v1/campaigns/:idDelete a draft campaign
POST/api/v1/campaigns/:id/sendTrigger a campaign send

List campaigns

GET/mail/v1/campaigns

List campaigns with optional status filter.

Query parameters

statusstringquery

Filter: draft, scheduled, sending, sent, paused, cancelled.

pagenumberquerydefault: 1

Page number.

limitnumberquerydefault: 20

Results per page (max 50).

Response fields

successboolean

true when the request succeeded.

dataArray<Campaign>

The page of campaigns. Each includes id, name, subject, status, from_email, from_name, segment_id, scheduled_at, started_at, completed_at, total_recipients, total_sent, total_delivered, total_opened, total_clicked, total_bounced, total_complained, created_at, and updated_at.

paginationobject

Pagination metadata: page, limit, total, totalPages.

200 — OK
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "February Newsletter",
      "subject": "What's new this month",
      "status": "sent",
      "from_email": "newsletter@yourdomain.com",
      "from_name": "Misar Team",
      "segment_id": "550e8400-e29b-41d4-a716-446655440001",
      "scheduled_at": "2026-02-01T10:00:00Z",
      "started_at": "2026-02-01T10:00:05Z",
      "completed_at": "2026-02-01T10:12:00Z",
      "total_recipients": 5000,
      "total_sent": 5000,
      "total_delivered": 4988,
      "total_opened": 1250,
      "total_clicked": 340,
      "total_bounced": 12,
      "total_complained": 2,
      "created_at": "2026-01-28T09:00:00Z",
      "updated_at": "2026-02-01T10:12:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 8, "totalPages": 1 }
}

Create a campaign

POST/mail/v1/campaigns

Create a new campaign. Plan limits apply.

Request body

namestringbodyrequired

Internal name (max 100 characters).

descriptionstringbody

Optional internal description (max 1000 characters).

subjectstringbodyrequired

Email subject line (supports {{variables}}, max 255 characters).

fromNamestringbodyrequired

Sender display name (max 100 characters).

fromEmailstringbodyrequired

Must be one of your connected email accounts.

replyTostringbody

Reply-to address.

segmentIdUUIDbody

Target audience segment.

templateIdUUIDbody

Use a template instead of inline HTML. Provide templateId or body content (one required).

bodyHtmlstringbody

Inline HTML body. Provide templateId or body content (one required).

bodyTextstringbody

Plain text fallback (recommended).

scheduledAtstringbody

ISO-8601 time to schedule the campaign (must be in the future). When set, the campaign is created with status scheduled; otherwise draft.

Response fields

successboolean

true when the campaign was created.

dataobject

The created campaign row, including id, name, status, and all campaign fields.

Request
{
  "name":        "February Newsletter",
  "subject":     "What's new this month 🚀",
  "fromName":   "Misar Team",
  "fromEmail":  "newsletter@yourdomain.com",
  "replyTo":    "support@yourdomain.com",
  "segmentId":  "550e8400-e29b-41d4-a716-446655440001",
  "templateId": "550e8400-e29b-41d4-a716-446655440002",
  "bodyHtml":   "<h1>Hello {{firstName}}!</h1>",
  "bodyText":   "Hello {{firstName}}!"
}
201 — Created
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "February Newsletter",
    "status": "draft"
  }
}

Errors

  • 403 — Campaign limit reached for your plan
  • 403 — fromEmail is not one of your connected accounts
  • 403 — templateId or segmentId not found or not owned by your account
  • 400 — Either templateId or body content is required

Update a campaign

PATCH/mail/v1/campaigns/:id

Update a campaign. Only campaigns in draft, scheduled, or paused status can be modified. Any subset of the fields below may be sent. For paused campaigns, only a status change is allowed.

Path parameters

idstringpathrequired

ID of the campaign to update.

Request body

namestringbody

Updated internal name.

descriptionstringbody

Updated internal description.

subjectstringbody

Updated subject line.

fromNamestringbody

Updated sender display name.

replyTostringbody

Updated reply-to address.

bodyHtmlstringbody

Updated HTML content.

bodyTextstringbody

Updated plain-text content.

segmentIdUUIDbody

Updated target segment.

scheduledAtstringbody

Updated ISO-8601 schedule time, or null to clear it.

statusstringbody

New status. Valid transitions: draft → scheduled/cancelled; scheduled → draft/paused/cancelled; paused → scheduled/cancelled.

Request
{
  "subject": "Updated subject line",
  "bodyHtml": "<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.

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

Trigger a campaign send

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

Trigger an immediate send of a campaign. The campaign must be in draft or scheduled status. This endpoint sends right away — it takes no request body. To schedule a campaign for a future time, set scheduledAt when creating or updating the campaign.

Path parameters

idstringpathrequired

ID of the draft or scheduled campaign.

Response fields

successboolean

true when the send was initiated.

messagestring

Confirmation message, e.g. Campaign send initiated.

campaignIdstring

ID of the campaign.

statusstring

Resulting status — scheduled (claimed for sending by the worker).

Request
curl -X POST https://api.misar.io/mail/v1/campaigns/550e8400-e29b-41d4-a716-446655440000/send \
  -H "Authorization: Bearer msk_your_key"
200 — OK
{
  "success": true,
  "message": "Campaign send initiated",
  "campaignId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "scheduled"
}

Errors

  • 400 — Campaign is not in draft or scheduled status
  • 400 — Invalid campaign ID format
  • 404 — Campaign not found
  • 409 — Campaign status changed before it could be claimed
  • 429 — Send rate limit exceeded

List Health

Monitor your mailing list quality, detect unengaged subscribers, score contacts, and run win-back workflows

Templates

Create and manage reusable email templates with merge tag support

On this page

EndpointsList campaignsCreate a campaignUpdate a campaignDelete a campaignTrigger a campaign send