API Keys

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

Key Format

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

Creating a Key

Available Scopes

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={ /* ... */ },
)

OAuth 2.0 (Authorization Code + PKCE)

For third-party integrations that act on behalf of a MisarMail user — such as ChatGPT Actions and Google Gemini — MisarMail supports the OAuth 2.0 Authorization Code flow with PKCE. Use this instead of a static msk_ key when a user grants a connected app access to their account.

The flow is the standard Authorization Code + PKCE exchange: redirect the user to the authorization endpoint with a code_challenge, then exchange the returned code for an access token at the token endpoint using the matching code_verifier. The resulting bearer token is sent the same way as an API key:

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

OAuth Scopes

Listing and Revoking Keys

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

Security Best Practices

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"
}