API Key Scopes

Scopes define what actions an API key can perform. Each scope grants access to specific endpoints and operations.

Scope names follow the pattern resource:action. The wildcard * grants all current and future permissions.

Available Scopes

Campaigns

Scope	Description
`campaigns:create`	Create new campaigns
`campaigns:read`	View campaigns and their details, including the flow graph
`campaigns:update`	Modify campaign configuration, sequences and subsequence branches
`campaigns:pause`	Pause active campaigns
`campaigns:activate`	Resume paused campaigns
`campaigns:archive`	Archive completed or paused campaigns
`campaigns:delete`	Delete campaigns
`campaigns:all`	Full access to campaigns — implies all seven above

Contacts

The contact directory is your team-wide set of people, independent of any campaign. See Contacts Overview.

Scope	Description
`contacts:create`	Create contacts or import them into the directory
`contacts:read`	View the contact directory, contact detail and contact lists
`contacts:update`	Update contact profiles, tags, signal overrides and list membership
`contacts:delete`	Delete contacts from the directory
`contacts:send_email`	Send a direct 1:1 email to a contact outside of any campaign — spends 1 credit per send
`contacts:all`	Full access to the contact directory — implies all five above, including `contacts:send_email`

contacts:send_email is deliberately separate from contacts:update. A key trusted to retag the directory is not thereby trusted to spend credits and put mail on the wire from it. Grant it only to integrations that should be able to send.

Leads

A lead is one person’s membership of one campaign; a contact is the person themselves.

Scope	Description
`leads:create`	Upload leads via CSV or add individual leads
`leads:read`	View lead data, engagement metrics and a lead’s journey through the campaign graph
`leads:update`	Update lead fields, and move leads into a subsequence branch by hand
`leads:delete`	Remove leads from campaigns (PENDING only)
`leads:all`	Full access to all lead operations

Sender Accounts

Scope	Description
`sender_accounts:create`	Add new sender accounts (ColdSend Native or SMTP)
`sender_accounts:read`	View sender account details and stats
`sender_accounts:delete`	Remove sender accounts
`sender_accounts:all`	Full access to all sender account operations

Domains

Scope	Description
`domains:create`	Add new custom domains
`domains:read`	View domains
`domains:activate`	Activate domains
`domains:delete`	Remove domains
`domains:all`	Full access to all domain operations

Replies

Scope	Description
`replies:read`	View conversations and reply threads
`replies:create`	Send replies to leads
`replies:update`	Mark threads as read or starred
`replies:all`	Full access to replies and conversations

Webhooks

Scope	Description
`webhooks:create`	Create webhook subscriptions
`webhooks:read`	View webhook subscriptions and delivery logs
`webhooks:update`	Update webhook subscriptions and send test events
`webhooks:delete`	Delete webhook subscriptions
`webhooks:all`	Full access to all webhook operations

Wildcard

Scope	Description
`*`	Full access to all resources. Automatically grants access to new scopes.

Only use * for administrative tools. Protect these keys accordingly — it grants contacts:send_email, so a wildcard key can spend credits.

Recommended Scope Groups

The dashboard offers these presets when minting a key:

Group	Scopes	Use for
`full_access`	`*`	Administrative tooling you control
`campaign_management`	`campaigns:all`, `leads:all`, `contacts:all`, `replies:all`	An integration that runs outreach end to end
`campaigns_only`	`campaigns:all`	Campaign automation without directory or inbox access
`contacts_only`	`contacts:all`	CRM sync — includes the ability to send direct email
`sender_accounts_only`	`sender_accounts:all`	Inbox provisioning
`domains_only`	`domains:all`	Domain and DNS setup
`webhooks_only`	`webhooks:all`	Event ingestion pipeline
`inbox_management`	`replies:read`, `replies:create`, `replies:update`	A shared-inbox or helpdesk integration
`read_only`	`campaigns:read`, `sender_accounts:read`, `domains:read`, `leads:read`, `contacts:read`, `replies:read`, `webhooks:read`	Reporting and dashboards

read_only deliberately grants no send capability of any kind — neither contacts:send_email nor replies:create.

Scope Checking

When an API request is made, ColdSend verifies the API key has the required scope:

Success Example

headers = {"X-API-Key": "cs_live_key_with_campaigns_read"}

response = requests.get(
    f"{base_url}/api/public/v1/campaigns",
    headers=headers
)
# Returns 200 OK

Insufficient Scope Example

{
  "detail": "Missing required scopes: campaigns:write",
  "required": ["campaigns:write"],
  "granted": ["sender_accounts:read"]
}

Status: 403 Forbidden

Best Practices

Principle of least privilege — Grant only the minimum scopes needed
Separate keys by function — Different integrations should use different keys
Audit regularly — Review which scopes your keys actually use
Use compound scopes — campaigns:all is cleaner than listing each scope individually

Next Steps

Authentication

Learn how to authenticate requests using API keys.

API Keys

Create and manage API keys for your integrations.

Direct Email

The one endpoint that spends credits, and the scope that guards it.

Webhooks

Subscribe to events instead of polling.

Getting Started

Authentication

Campaigns

Sender Accounts

Domains

Contacts

Leads

Replies

Analytics

Webhooks

Reference

Compliance

Available Scopes

Campaigns

Contacts

Leads

Sender Accounts

Domains

Replies

Webhooks

Wildcard

Recommended Scope Groups

Scope Checking

Success Example

Insufficient Scope Example

Best Practices

Next Steps

Authentication

API Keys

Direct Email

Webhooks

​Available Scopes

​Campaigns

​Contacts

​Leads

​Sender Accounts

​Domains

​Replies

​Webhooks

​Wildcard

​Recommended Scope Groups

​Scope Checking

​Success Example

​Insufficient Scope Example

​Best Practices

​Next Steps

Authentication

API Keys

Direct Email

Webhooks

Available Scopes

Campaigns

Contacts

Leads

Sender Accounts

Domains

Replies

Webhooks

Wildcard

Recommended Scope Groups

Scope Checking

Success Example

Insufficient Scope Example

Best Practices

Next Steps