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 to subscriber lists
`templates:read`	Read templates
`templates:write`	Create and update templates
`senders:read`	Read sender identities
`senders:write`	Create and update sender identities
`analytics:read`	Access analytics and reports
`campaigns:read`	Read campaigns and campaign analytics
`lists:read`	Read subscriber lists
`domains:read`	Read sending domains and DNS status
`domains:write`	Add and verify sending domains
`contacts:read`	Read contacts
`contacts:write`	Create and update contacts
`providers:read`	Read configured provider status
`org:read`	Read organization details
`org:write`	Update organization details
`*`	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 use a standard envelope with the result under data, a requestId for support/debugging, and pagination on list endpoints:

{
  "data": { "id": "...", "status": "sent" },
  "requestId": "req_...",
  "pagination": { "page": 1, "perPage": 25, "total": 3 }
}

Error responses always return an error field with a human-readable message. Errors from v1 endpoints also include a machine-readable code and the requestId; authentication failures return only error:

{
  "error": "Template not found",
  "code": "NOT_FOUND",
  "requestId": "req_..."
}

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