API Keys
Create, manage, and secure your MisarMail API keys
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 hexCreating 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.mail.misar.io/v1/send \
-H "Authorization: Bearer msk_your_key_here" \
-H "Content-Type: application/json" \
-d '{...}'const res = await fetch("https://api.mail.misar.io/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.mail.misar.io/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"
}