Sandbox API Keys

​

How Sandbox Keys Work

1. Recipients are overridden — all to, cc, and bcc addresses are replaced with the email address of the user who created the key.
2. The sender domain is overridden — the from address domain is rewritten to dev.uselettr.com, a pre-verified sandbox domain. The local part (before @) is preserved.
3. No domain verification required — you don’t need to set up or verify a sending domain to start testing.
4. No billing impact — sandbox sends are free and don’t count against your monthly sending quota or daily limits.
5. Traffic is isolated — sandbox emails are sent through a dedicated subaccount, fully separated from your live sending traffic.

​

Key Format

lttr_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​

Creating a Sandbox Key

1. Navigate to Settings > API Keys in your dashboard
2. Click Create API Key
3. Enter a descriptive name (e.g., “Local Development”, “CI Tests”)
4. Select your desired permission level
5. Set the Type to Sandbox
6. Click Create

​

Rate Limits

X-Sandbox-RateLimit-Minute-Limit: 10
X-Sandbox-RateLimit-Minute-Remaining: 9
X-Sandbox-RateLimit-Day-Limit: 100
X-Sandbox-RateLimit-Day-Remaining: 99

​

Allowed Endpoints

• POST /api/emails — Send an email
• GET /api/emails — List sent emails
• GET /api/emails/{requestId} — Get email details
• GET /api/emails/events — List email events
• POST /api/emails/scheduled — Schedule an email
• GET /api/emails/scheduled/{transmissionId} — Get scheduled email details
• DELETE /api/emails/scheduled/{transmissionId} — Cancel a scheduled email
• GET /api/templates — List templates
• GET /api/templates/{slug} — Get template details
• GET /api/templates/{slug}/merge-tags — Get template merge tags
• GET /api/domains — List domains
• GET /api/domains/{domain} — Get domain details
• GET /api/webhooks — List webhooks
• GET /api/webhooks/{webhookId} — Get webhook details
• GET /api/auth/check — Verify API key validity

• POST /api/templates — Create a template
• PUT /api/templates/{slug} — Update a template
• DELETE /api/templates/{slug} — Delete a template
• POST /api/domains — Create a domain
• POST /api/domains/{domain}/verify — Verify a domain
• DELETE /api/domains/{domain} — Delete a domain
• POST /api/webhooks — Create a webhook
• PUT /api/webhooks/{webhookId} — Update a webhook
• DELETE /api/webhooks/{webhookId} — Delete a webhook
• POST /api/sms — Send SMS
• POST /api/whatsapp — Send WhatsApp message

{
  "status": "error",
  "error_code": "sandbox_restricted",
  "message": "Sandbox API keys are restricted to email sending and read-only endpoints."
}

​

Data Isolation

• Sent email lists only show emails sent to the key owner’s address
• Email event lists are filtered to the key owner’s address
• Scheduled email details are only accessible if the key owner is a recipient
• Cancelling scheduled emails requires the key owner to be a recipient

​

Viewing Sandbox Events in the Dashboard

​

Example Usage

curl https://app.lettr.com/api/emails \
  -X POST \
  -H "Authorization: Bearer lttr_sandbox_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": ["customer@example.com"],
    "subject": "Order Confirmation #1234",
    "html": "<h1>Thank you for your order!</h1>"
  }'

​

When to Use Sandbox Keys

​

Next Steps