Skip to main content
When creating an API key, you assign a permission level that controls which API endpoints the key can access. Lettr supports two dashboard permission levels — Full Access and Sending Only — plus a Custom scope system available via the API.

​
Permission Levels

​
Full Access

Full Access keys provide complete access to all API endpoints and operations:
  • Send emails via API
  • List and retrieve sent email details
  • Access and manage email templates
  • Create, verify, and delete sending domains
  • Configure and manage webhooks
  • List projects
Use Full Access keys for:
  • Backend services that need complete platform control
  • Administrative tools and dashboards
  • CI/CD pipelines that manage domains and templates
  • Internal tools requiring access to all resources

​
Sending Only

Sending Only keys are restricted to email sending operations only. Requests to any other endpoint will be rejected with a 403 Forbidden response: 
{
  "message": "Your API key does not have the required permissions for this action.",
  "error_code": "insufficient_scope"
}
Use Sending Only keys for:
  • Production applications that only send transactional emails
  • Third-party integrations that don’t need administrative access
  • Services where you want to limit the blast radius of a potential key compromise

​
Custom

Custom scopes provide fine-grained access control by letting you specify exactly which operations a key can perform. Custom scopes are currently available via the API and DynamoDB — a dashboard UI for selecting individual scopes is coming soon.

​
Available Scopes

ScopeDescription
emails:sendSend emails via API
emails:readList and retrieve sent email details and events
templates:readList and retrieve templates
templates:writeCreate, update, and delete templates
domains:readList and retrieve domains
domains:writeCreate, verify, and delete domains
webhooks:readList and retrieve webhooks
webhooks:writeCreate, update, and delete webhooks
projects:readList projects
sms:sendSend SMS messages
whatsapp:sendSend WhatsApp messages
audience:readList and retrieve contacts, lists, and segments
audience:writeCreate, update, and delete contacts, lists, and segments
The Full Access preset includes all 13 scopes. The Sending Only preset includes emails:send, sms:send, and whatsapp:send.
Use Custom keys for:
  • Template management services that only need templates:read and templates:write
  • Webhook automation tools that only need webhooks:read and webhooks:write
  • Audience management integrations that need audience:read and audience:write without sending permissions
  • Monitoring dashboards that only need read scopes (emails:read, domains:read, etc.)

​
Creating Keys with Specific Permissions

​
Via the Dashboard

  1. Navigate to Settings > API Keys
  2. Click Create API Key
  3. Enter a descriptive name
  4. Select the permission level:
    • Full Access — Complete access to all endpoints
    • Sending Only — Restricted to email, SMS, and WhatsApp sending
    • Custom — Select individual scopes (coming soon to the dashboard; available via API)
  5. Configure optional IP restrictions
  6. Click Create

​
IP Restrictions

In addition to permission levels, you can further secure your API keys by restricting them to specific IP addresses. This provides defense in depth — even if a key is compromised, it cannot be used from unauthorized locations.

​
Configuring IP Restrictions

When creating or editing an API key, you can specify allowed IP addresses in the Allowed IPs field: 
203.0.113.50, 198.51.100.0/24, 10.0.0.1

​
Supported Formats

FormatExampleDescription
Single IP203.0.113.50Allow a single IP address
CIDR notation198.51.100.0/24Allow a range of 256 IPs (198.51.100.0 - 198.51.100.255)
Multiple entries10.0.0.1, 10.0.0.2Comma-separated list of IPs or ranges

​
CIDR Notation Reference

CIDRIP Range SizeExample
/321 IPSingle host
/24256 IPs10.0.0.0 - 10.0.0.255
/1665,536 IPs10.0.0.0 - 10.0.255.255
/816,777,216 IPs10.0.0.0 - 10.255.255.255
If no IP restrictions are configured, the API key can be used from any IP address. We recommend configuring IP restrictions for production keys.

​
IP Restriction Errors

When a request is made from a non-whitelisted IP: 
{
  "message": "Access denied. Your IP address is not allowed."
}
HTTP Status: 403 Forbidden

​
Updating Key Permissions

You can change the permission level of an existing API key at any time:
  1. Navigate to Settings > API Keys
  2. Click the actions menu (three dots) next to the key
  3. Select Edit
  4. Update the permission level
  5. Click Save
Permission changes take effect immediately. If you downgrade a key from Full Access to Sending Only, any non-sending API requests using that key will be rejected right away.

​
Security Recommendations

Use different API keys for development, staging, and production environments. This allows you to revoke keys independently and track usage per environment.
Production Web Server - Full Access
Staging Environment - Full Access
Development - Full Access
CI/CD Pipeline - Full Access
For maximum security, restrict production API keys to your server’s IP addresses or IP ranges. This adds a layer of protection even if a key is compromised.
Review which keys are being used and their access patterns. Revoke any keys that are no longer needed or show suspicious activity.
Use descriptive names that clearly indicate each key’s purpose, environment, and owner. This makes it easier to manage keys over time.

​
Managing Multiple Keys

For larger organizations or complex deployments, consider creating separate keys for:
PurposeIP Restrictions
Production email sendingProduction server IPs
Admin dashboardOffice IP range
CI/CD pipelineCI service IPs
Monitoring serviceMonitoring service IPs
Development testingNone (or developer IPs)
This approach provides:
  • Isolation: Compromise of one key doesn’t affect others
  • Traceability: Clear audit trail of which system performed which action
  • Flexibility: Independent rotation and revocation schedules

​
Next Steps

API Keys Introduction

Learn how to create and manage API keys

Sending Emails

Start sending emails with your API key