API Keys

All MisarMail API requests authenticate with an API key. Keys are scoped, revocable, and tied to your account.

Format: msk_ + 64 hex chars. Header: Authorization: Bearer msk_.... Create in Settings → API Keys. Key shown once — store it immediately.

Key Format

msk_a1b2c3d4e5f6...   # 68 characters total: msk_ + 64 hex

Creating a Key

Go to Settings → API Keys

Give your key a name (e.g., "Production", "MisarDev Integration")

Choose the scopes your integration requires (see table below)

The full key is shown exactly once. Copy it to a password manager or secrets vault immediately.

You cannot retrieve the key secret after creation. If lost, revoke it and create a new one.

Available Scopes

Scope	Access
`send`	Send transactional and marketing emails
`send:transactional`	Send transactional emails only
`send:marketing`	Send marketing/campaign emails only
`contacts`	Full contact CRUD
`campaigns`	Campaign management
`templates`	Template management
`automations`	Automation workflows
`analytics`	Analytics and reporting
`validate`	Email validation
`track`	Event and purchase tracking
`track:events`	Custom event tracking only
`track:purchase`	Purchase event tracking only
`inbound`	Inbound email domain management
`inbound:read`	Read inbound config
`inbound:write`	Create/update inbound config
`ips`	Dedicated IP management
`ips:read`	Read IP config
`ips:write`	Manage IPs
`sandbox`	Sandbox mode access
`monetization`	Tip/monetization features
`read`	Read-only access to contacts and tests

Use the most restrictive scopes needed for your integration. A key used only for sending transactional emails should have send:transactional, not the broader send scope.

Using a Key

Include the key in every request using the Authorization: Bearer header:

curl https://api.misar.io/mail/v1/send \
  -H "Authorization: Bearer msk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{...}'

const res = await fetch("https://api.misar.io/mail/v1/send", {
  headers: {
    Authorization: `Bearer ${process.env.MISARMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({ /* ... */ }),
});

import os, requests

requests.post(
    "https://api.misar.io/mail/v1/send",
    headers={"Authorization": f"Bearer {os.environ['MISARMAIL_API_KEY']}"},
    json={ /* ... */ },
)

Listing and Revoking Keys

Key management endpoints require a Supabase session cookie — use them from the MisarMail settings UI, not from external apps.

Method	Endpoint	Purpose
`GET`	`/api/v1/keys`	List your keys (prefix only — secret never returned)
`POST`	`/api/v1/keys`	Create a new key
`DELETE`	`/api/v1/keys?id=<uuid>`	Revoke a key immediately

Security Best Practices

Environment Variables

Store keys in .env files. Never hardcode in source code.

One Key Per App

Use separate keys for dev, staging, and production environments.

Rotate Regularly

Revoke old keys and create new ones periodically.

Git Ignore

Add .env and .env.local to .gitignore.

Error Responses

401 — Invalid Key

{
  "success": false,
  "error": "Invalid or missing API key. Use: Authorization: Bearer msk_..."
}

403 — Wrong Sender

{
  "success": false,
  "error": "'from.email' is not a verified account for this API key"
}

403 — Missing Scope

{
  "success": false,
  "error": "API key does not have 'send' scope"
}