Authentication

API keys, session authentication, and authorization scopes for the NevarMail API.

NevarMail supports two authentication methods: session-based authentication for the dashboard, and API key authentication for programmatic access.

Session authentication

When you sign in through the NevarMail dashboard, a session cookie is automatically managed. All requests from the dashboard UI use this session for authentication. No additional configuration is required.

API key authentication

For programmatic access, include your API key in the request headers:

curl -X POST https://your-instance.com/api/email/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"to":"user@example.com","subject":"Hello","text":"Hi there"}'

Generating API keys

API keys can be generated from the Settings page in the dashboard. Each key can be scoped to specific permissions.

Key scopes

Scope	Description
`email:send`	Send emails and scheduled emails
`email:read`	Read email history and status
`templates:manage`	Create, update, and delete templates
`templates:read`	Read templates
`senders:manage`	Create, update, and delete senders
`senders:read`	Read sender identities
`providers:manage`	Configure email providers
`providers:read`	Read provider status and health
`analytics:read`	Access analytics and reports
`inbound:manage`	Configure inbound routing rules
`domains:manage`	Manage sending domains
`*`	Full access (all scopes)

Request headers

All API requests should include:

Header	Required	Description
`Content-Type`	Yes (POST/PUT)	Must be `application/json`
`Authorization`	Yes	`Bearer YOUR_API_KEY`

Response format

Success responses return the data directly at the top level (no wrapper envelope):

{
  "id": "...",
  "status": "sent"
}

Error responses return an error field with a human-readable message:

{
  "error": "Invalid API key"
}

Rate limiting

API requests are subject to rate limits based on your plan tier. See Rate Limits for details.

Security best practices

Rotate keys regularly -- Generate new API keys periodically and revoke old ones
Use minimal scopes -- Only grant the permissions each key actually needs
Keep keys secret -- Never expose API keys in client-side code or public repositories
Use environment variables -- Store keys in environment variables, not in code

Authentication

On this page