API Keys Introduction

API keys authenticate your requests to the Lettr API. Each key is associated with a specific team and can be configured with different permission levels and IP restrictions for enhanced security.

Creating API Keys

You can create API keys through the Lettr dashboard:

Navigate to Settings > API Keys in your dashboard
Click Create API Key
Enter a descriptive name for the key (e.g., “Production Server”, “Staging Environment”)
Select the appropriate permission level
Optionally, configure IP restrictions
Click Create

The full API key is only displayed once upon creation. Copy and store it securely immediately. You will not be able to view the complete key again.

Key Types

Lettr supports two API key types:

Live — for production use. Sends real emails to actual recipients and counts against your billing quota.
Sandbox — for testing. Redirects all emails to your own inbox, uses a sandbox sending domain, and doesn’t affect billing. See the Sandbox API Keys guide for details.

Key Format

Lettr API keys follow this format:

lttr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sandbox keys have a distinct prefix:

lttr_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

lttr_ prefix identifies it as a live Lettr API key
lttr_sandbox_ prefix identifies it as a sandbox key
Followed by a 64-character cryptographically secure random string

Using API Keys

Authorization Header (Recommended)

Include your API key in the Authorization header using the Bearer scheme:

curl https://app.lettr.com/api/emails \
  -X POST \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"from": "sender@example.com", "to": ["recipient@example.com"], "subject": "Hello", "html": "<p>Hello!</p>"}'

In SDKs

When using official Lettr SDKs, pass your API key during client initialization:

import { Lettr } from 'lettr';

const lettr = new Lettr(process.env.LETTR_API_KEY);

Permission Levels

When creating an API key, you can choose between two permission levels:

Full Access — grants access to all API endpoints, including sending emails, managing templates, domains, webhooks, and projects.
Sending Only — restricted to sending operations only (emails, SMS, and WhatsApp). Requests to any other endpoint will be rejected with a 403 Forbidden response.

Permission levels are fully enforced. Choose the level that matches your use case, and apply the principle of least privilege by using Sending Only keys wherever full access isn’t needed.

IP Restrictions

For additional security, you can restrict API keys to specific IP addresses or ranges:

Single IP: 203.0.113.50
CIDR notation: 198.51.100.0/24
Multiple entries: Combine IPs and ranges separated by commas

When IP restrictions are configured, requests from non-whitelisted IPs will receive a 403 Forbidden response.

Managing API Keys

Viewing Your Keys

Access your API keys in the dashboard at Settings > API Keys. The list displays:

Key name
First 12 characters of the key (masked for security)
Permission level
IP restriction status
Active status

Updating a Key

You can modify the following properties of an existing API key:

Name
Permission level
IP restrictions

The API key value itself cannot be changed. If you need a new key value, create a new key and delete the old one.

Revoking a Key

To revoke an API key:

Navigate to Settings > API Keys
Click the actions menu (three dots) next to the key
Select Delete
Type the key name to confirm deletion
Click Delete to confirm

Revoking a key is immediate and permanent. Any applications using the key will immediately stop working. Ensure you have updated all applications using the key before revoking it.

Best Practices

Never expose keys in client-side code

API keys should only be used server-side. Never include them in frontend JavaScript, mobile apps, or any code that runs on user devices. Exposed keys can be extracted and abused.

Use environment variables

Store API keys in environment variables rather than hardcoding them in your source code. This prevents accidental exposure through version control systems.

# .env file (never commit this)
LETTR_API_KEY=lttr_xxxxxxxxxxxx

Apply the principle of least privilege

Create keys with only the permissions required for their specific purpose. Use Sending Only keys for applications that don’t need full access.

Configure IP restrictions for production

Restrict production API keys to your server’s IP addresses or IP ranges. This adds a layer of security even if a key is compromised.

Use descriptive names

Give each API key a clear, descriptive name that identifies its purpose and the application or environment using it (e.g., “Production Web Server”, “Staging Environment”, “CI/CD Pipeline”).

Rotate keys periodically

Establish a key rotation schedule. Create a new key, update your applications to use it, then revoke the old key. This limits the window of exposure if a key is compromised.

Monitor API key usage

Review your API request logs regularly to detect unusual patterns that might indicate a compromised key.

Authentication Errors

Missing API Key

If no API key is provided, you’ll receive:

{
  "message": "API key is required."
}

HTTP Status: 401 Unauthorized

Invalid API Key

If the provided API key doesn’t exist or has been revoked:

{
  "message": "Invalid API key."
}

HTTP Status: 401 Unauthorized

IP Not Allowed

If the request comes from an IP address not in the key’s whitelist:

{
  "message": "Access denied. Your IP address is not allowed."
}

HTTP Status: 403 Forbidden

API Endpoints

The following endpoints are available when authenticated with an API key:

Endpoint	Method	Description
`/api/emails`	POST	Send an email
`/api/emails`	GET	List sent emails
`/api/emails/{requestId}`	GET	Get email details
`/api/templates`	GET	List templates
`/api/templates`	POST	Create a template
`/api/templates/{slug}`	GET	Get template details
`/api/templates/{slug}`	PUT	Update a template
`/api/templates/{slug}`	DELETE	Delete a template
`/api/templates/{slug}/merge-tags`	GET	Get template merge tags
`/api/templates/html`	GET	Get rendered template HTML
`/api/projects`	GET	List projects
`/api/domains`	GET	List domains
`/api/domains`	POST	Create a domain
`/api/domains/{domain}`	GET	Get domain details
`/api/domains/{domain}/verify`	POST	Verify a domain
`/api/domains/{domain}`	DELETE	Delete a domain
`/api/webhooks`	GET	List webhooks
`/api/webhooks/{webhookId}`	GET	Get webhook details
`/api/health`	GET	Health check
`/api/auth/check`	GET	Verify API key validity

Next Steps

Permissions

Learn more about API key permission levels and how to configure them

Sandbox API Keys

Test your integration safely without sending to real recipients

Send Your First Email

Get started with sending emails using your API key

Documentation

Quickstart

Learn

Integrations

API Keys Introduction

Creating API Keys

Key Types

Key Format

Using API Keys

Authorization Header (Recommended)

In SDKs

Permission Levels

IP Restrictions

Managing API Keys

Viewing Your Keys

Updating a Key

Revoking a Key

Best Practices

Authentication Errors

Missing API Key

Invalid API Key

IP Not Allowed

API Endpoints

Next Steps

Permissions

Sandbox API Keys

Send Your First Email

Documentation

Quickstart

Learn

Integrations

​Creating API Keys

​Key Types

​Key Format

​Using API Keys

​Authorization Header (Recommended)

​In SDKs

​Permission Levels

​IP Restrictions

​Managing API Keys

​Viewing Your Keys

​Updating a Key

​Revoking a Key

​Best Practices

​Authentication Errors

​Missing API Key

​Invalid API Key

​IP Not Allowed

​API Endpoints

​Next Steps

Permissions

Sandbox API Keys

Send Your First Email

Creating API Keys

Key Types

Key Format

Using API Keys

Authorization Header (Recommended)

In SDKs

Permission Levels

IP Restrictions

Managing API Keys

Viewing Your Keys

Updating a Key

Revoking a Key

Best Practices

Authentication Errors

Missing API Key

Invalid API Key

IP Not Allowed

API Endpoints

Next Steps