API Overview
MisarMail REST API — send emails, manage contacts, run campaigns, and more
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://mail.misar.io/apiAll API paths in this documentation are relative to this base. For example, POST /v1/send means POST https://mail.misar.io/api/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://mail.misar.io/api/v1/send \
-H "Authorization: Bearer msk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "hello@yourdomain.com", "name": "Your App" },
"to": [{ "email": "user@example.com" }],
"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 |
| Campaigns | GET/POST/PATCH/DELETE /v1/campaigns |
| 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 |
| Email Validation | GET/POST /v1/validate |
| Inbound Email | GET/POST/DELETE /v1/inbound |
Multi-Channel & Testing
| Category | Endpoints |
|---|---|
| Multi-Channel | POST /v1/channels/whatsapp/send, POST /v1/channels/push/send |
| A/B Testing | GET/POST /v1/ab-tests, POST /v1/ab-tests/:id/winner |
| Sandbox Mode | GET/DELETE /v1/sandbox (+ X-MisarMail-Sandbox header) |
Analytics & Tracking
| Category | Endpoints |
|---|---|
| Analytics | GET /v1/analytics/overview, POST /v1/track/event, POST /v1/track/purchase |
| Webhooks | Outbound + inbound event notifications |
Account & Billing
| Category | Endpoints |
|---|---|
| Accounts | GET/POST/DELETE /accounts (session auth) |
| Billing | GET /billing/subscription, POST /billing/checkout |
| Plan Limits | GET /v1/usage |