All articles › API & Developer

API Key Scopes

Understand read and write permissions per resource

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:write access.
  • 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.

Was this helpful?

Copy for AI (Markdown)

Related articles

Mailnaptic · Help center