Authentication

MisarMail uses Bearer token authentication. Every request to api.misar.io/mail/v1 must include an Authorization header.

API Keys

Create an API key

1. Go to Dashboard → Settings → API Keys
2. Click New API Key
3. Choose a name and select the scopes you need
4. Copy the key — it is only shown once

Keys are prefixed msk_ (MisarMail secret key).

Use the key

curl https://api.misar.io/mail/v1/send \
  -H "Authorization: Bearer msk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":[{"email":"[email protected]"}],"subject":"Hello","html":"<p>Hi</p>"}'

Scopes

API keys can be restricted to specific operations.

| Scope | Grants access to | |-------|-----------------| | send | Send transactional and marketing emails | | send:transactional | Send transactional emails only | | send:marketing | Send marketing campaigns only | | read | Read campaigns, contacts, analytics | | write | Create and update campaigns, contacts, templates | | contacts | Full contact management (read + write) | | validate | Email address validation | | inbound | Configure inbound email domains | | ips | Manage dedicated IP pools | | analytics | Read analytics and reports | | sandbox | Send in test mode (no real delivery) |

OAuth 2.0

Third-party integrations (Zapier, custom apps) can authenticate via OAuth 2.0 Authorization Code + PKCE.

Endpoints

| Endpoint | URL | |----------|-----| | Authorization | https://api.misar.io/mail/oauth/authorize | | Token exchange | https://api.misar.io/mail/oauth/token | | Token revocation | https://api.misar.io/mail/oauth/revoke | | Register app | https://api.misar.io/mail/oauth/register |

Authorization flow

GET https://api.misar.io/mail/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=read+write
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

Exchange the code for an access token:

POST https://api.misar.io/mail/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&client_id=YOUR_CLIENT_ID
&redirect_uri=https://yourapp.com/callback
&code_verifier=PKCE_VERIFIER

Response:

{
  "access_token": "msk_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Errors

Authentication failures return standard HTTP status codes:

| Status | Meaning | |--------|---------| | 401 | Missing or invalid API key | | 403 | Key exists but lacks the required scope | | 429 | Rate limit exceeded |

{
  "error": "Unauthorized",
  "message": "Invalid API key or insufficient scope",
  "success": false
}