POST /v1/send

Send a transactional email. Requires an API key with the send scope.

POST https://mail.misar.io/api/v1/send
Authorization: Bearer msk_your_key
Content-Type: application/json

Request Body

{
  "from":    { "email": "no-reply@yourdomain.com", "name": "Your App" },
  "to":      [{ "email": "user@example.com", "name": "User Name" }],
  "subject": "Welcome to Your App",
  "html":    "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  "text":    "Welcome! Thanks for signing up."
}

Fields

Field	Type	Required	Notes
`from.email`	string	✓	Must be a verified account owned by the API key
`from.name`	string	—	Display name shown in email clients
`to`	array	✓	Up to 100 recipients: `[{ email, name? }]`
`cc`	array	—	Up to 50 CC recipients
`bcc`	array	—	Up to 50 BCC recipients
`reply_to`	object	—	`{ email, name? }`
`subject`	string	✓	Max 998 characters
`html`	string	✓ (one of)	HTML email body
`text`	string	✓ (one of)	Plain text fallback — both recommended
`alias_id`	UUID	—	Route via a specific SMTP pool
`idempotency_key`	string	—	Prevent duplicate sends (max 128 chars)
`tags`	string[]	—	Up to 10 tags for filtering in analytics
`metadata`	object	—	Custom key-value data (string values)

Either html or text is required — providing both is strongly recommended. Many email clients render only plain text.

Response — 200 Sent

{
  "success":    true,
  "message_id": "msg_abc123",
  "provider":   "smtp-pool-name",
  "timestamp":  "2026-03-20T12:00:00.000Z"
}

Response — 202 Queued

{
  "success": false,
  "queued":  true,
  "message": "Email queued for retry"
}

A 202 response means the primary SMTP provider was temporarily unavailable. The email is automatically retried — this is not an error, do not retry manually.

Code Examples

cURL

curl https://mail.misar.io/api/v1/send \
  -H "Authorization: Bearer msk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from":    { "email": "hello@yourdomain.com", "name": "Your App" },
    "to":      [{ "email": "user@example.com" }],
    "subject": "Welcome!",
    "html":    "<h1>Welcome!</h1><p>Thanks for joining.</p>",
    "text":    "Welcome! Thanks for joining."
  }'

Node.js

const response = await fetch("https://mail.misar.io/api/v1/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MISARMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from:    { email: "hello@yourdomain.com", name: "Your App" },
    to:      [{ email: "user@example.com" }],
    subject: "Welcome!",
    html:    "<h1>Welcome!</h1><p>Thanks for joining.</p>",
    text:    "Welcome! Thanks for joining.",
    idempotency_key: `welcome-${userId}`,
  }),
});

const data = await response.json();
if (!response.ok && !data.queued) {
  throw new Error(data.error || "Failed to send email");
}

Python

import os, requests

response = requests.post(
    "https://mail.misar.io/api/v1/send",
    headers={
        "Authorization": f"Bearer {os.environ['MISARMAIL_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "from":    {"email": "hello@yourdomain.com", "name": "Your App"},
        "to":      [{"email": "user@example.com"}],
        "subject": "Welcome!",
        "html":    "<h1>Welcome!</h1><p>Thanks for joining.</p>",
        "text":    "Welcome! Thanks for joining.",
        "idempotency_key": f"welcome-{user_id}",
    },
)
data = response.json()
if not response.ok and not data.get("queued"):
    raise Exception(data.get("error", "Failed to send email"))

Idempotency

Use idempotency_key to prevent duplicate emails when retrying failed requests:

{ "idempotency_key": "welcome-usr_abc123" }

If a request with the same key was already delivered within 24 hours, the API returns the original result without re-sending. Use a unique key per logical event (e.g., welcome-<userId>, invoice-<invoiceId>).

SMTP Pool Routing

By default, emails route through the best available SMTP pool. To force a specific pool (e.g., transactional vs. promotional), pass alias_id:

{ "alias_id": "550e8400-e29b-41d4-a716-446655440000" }

Find alias IDs in Settings → SMTP Pools.