API Key Scopes
Understand read and write permissions per resource
API Key Scopes
Every Mailnaptic API key is created with a specific set of scopes that control which resources it can access and what operations it can perform. Scopes follow a resource:action pattern, where the resource is the type of data and the action is either read or write.
How scopes work
When an API request is made, Mailnaptic checks whether the API key has the required scope for that endpoint. If the key lacks the necessary scope, the request is rejected with a 403 Forbidden response:
{
"success": false,
"error": "API key does not have the required scope: contacts:write",
"code": "FORBIDDEN"
}Available scopes
| Scope | Grants access to |
|---|---|
contacts:read | List contacts, get contact details, view tags, view activity |
contacts:write | Create, update, and delete contacts; manage tags and list memberships |
lists:read | List all lists, get list details and member counts |
lists:write | Create, update, and delete lists |
segments:read | List segments, get segment details and member previews |
segments:write | Create, update, and delete segments |
campaigns:read | List campaigns, get campaign details and analytics |
campaigns:write | Create, update, schedule, and send campaigns |
transactional:send | Send transactional emails via the API |
domains:read | List domains and view DNS verification status |
domains:write | Add and remove sending domains |
organization:read | View organization settings and metadata |
organization:write | Update organization settings |
webhooks:read | List webhook endpoints and delivery logs |
webhooks:write | Create, update, and delete webhook endpoints |
Read vs. write scopes
A :write scope includes the corresponding :read scope. For example, a key with contacts:write can also read contacts — you do not need to add contacts:read separately.
The transactional:send scope is a special scope that only grants the ability to send transactional emails. It does not include read or write access to campaigns or contacts.
Recommended scope combinations
Match your API key's scopes to its intended use case:
| Use case | Recommended scopes |
|---|---|
| Website signup form | contacts:write, lists:read |
| Transactional email service | transactional:send |
| CRM bidirectional sync | contacts:write, lists:read, segments:read |
| Analytics dashboard | campaigns:read, contacts:read |
| Full automation | contacts:write, campaigns:write, lists:write, segments:write |
| Webhook management | webhooks:write |
Security best practices
- Principle of least privilege: Only grant the scopes a key actually needs. A key used only to add subscribers should not have
campaigns:writeaccess. - Separate keys per integration: Create a dedicated key for each service or application. If one is compromised, you can revoke it without affecting other integrations.
- Audit regularly: Review your API keys and their scopes periodically. Revoke keys that are no longer needed.
Note: Scopes are set at key creation time and cannot be changed afterward. To modify scopes, create a new key with the desired permissions and revoke the old one.