MisarMail API

The MisarMail API lets you programmatically send transactional emails, manage contacts, create campaigns, and access all platform features — the same operations available through the dashboard UI.

Base URL

https://api.misar.io/mail

All API paths in this documentation are relative to this base. For example, POST /v1/send means POST https://api.misar.io/mail/v1/send.

Versioning

Current version: v1

Routes under /api/v1/ are stable. Breaking changes will be announced and versioned. Routes under /api/ (without /v1/) are session-authenticated UI routes.

Authentication

Two authentication methods:

Method	Header	Use Case
API Key	`Authorization: Bearer msk_...`	Programmatic access, integrations
Session Cookie	Automatic (browser)	Dashboard UI

For programmatic access, always use an API key. See Authentication.

Error Format

All errors return JSON with success: false:

{
  "success": false,
  "error": "Human-readable error message"
}

Validation errors (400) add a details field:

{
  "success": false,
  "error": "Validation failed",
  "details": { "fieldErrors": { "to": ["Must have at least 1 recipient"] } }
}

See Error Codes for the full reference.

Plan Limits

All API operations respect the same plan limits as the dashboard UI. A free-plan user cannot create custom domains via API any more than via the UI. See Plan Limits for the full feature matrix.

Quick Start

# 1. Create an API key at mail.misar.io/settings/api-keys

# 2. Send your first email
curl https://api.misar.io/mail/v1/send \
  -H "Authorization: Bearer msk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from":    { "email": "[email protected]", "name": "Your App" },
    "to":      [{ "email": "[email protected]" }],
    "subject": "Hello from MisarMail",
    "html":    "<p>Hello world!</p>",
    "text":    "Hello world!"
  }'

Available Endpoints

Core

Category	Endpoints
Send Email	`POST /v1/send`
Contacts	`GET/POST/PATCH/DELETE /v1/contacts`, `POST /v1/contacts/import`
Campaigns	`GET/POST/PATCH/DELETE /v1/campaigns`, `POST /v1/campaigns/:id/send`
Templates	`GET/POST /v1/templates`, `POST /v1/templates/render`
Automations	`GET/POST/PATCH /v1/automations`

Deliverability & Infrastructure

Category	Endpoints
Custom Domains	`GET/POST/DELETE /v1/domains`
Email Aliases	`GET/POST/PATCH/DELETE /v1/aliases`
Dedicated IPs	`GET/POST/PATCH/DELETE /v1/dedicated-ips` — Max plan
Email Validation	`POST /v1/validate` — Pro plan
Inbound Email	`GET/POST/DELETE /v1/inbound`

Testing

Category	Endpoints
A/B Testing	`GET/POST /v1/ab-tests`, `POST /v1/ab-tests/:id/winner` — Pro plan
Sandbox Mode	`GET/DELETE /v1/sandbox` (+ `X-MisarMail-Sandbox` header)

AI Features

Category	Endpoints
AI Subject Lines	`POST /v1/ai/subject-lines` — Pro plan

Analytics & Tracking

Category	Endpoints
Analytics	`GET /v1/analytics`, `POST /v1/track/event`, `POST /v1/track/purchase`
Webhooks	Outbound + inbound event notifications

Account & Billing

Category	Endpoints
API Keys	`GET/POST/DELETE /v1/keys`
Accounts	`GET/POST/DELETE /accounts` (session auth)
Billing	`GET /billing/subscription`, `POST /billing/checkout`
Plan Limits	`GET /v1/usage` — full quota + feature flag response

Dashboard Features

These features are available via the dashboard UI (session-cookie authentication). They are not accessible with API keys.

Feature	Description
Workspaces	Multi-workspace management for agencies and teams — Max plan

API Overview