Guides
API keys
Every key belongs to one project and one environment, and either sends only or has full access.
Last reviewed
On this page (6)
Every key belongs to one project and one environment. A key only ever sees its own project, and messages sent with it only in its own environment.
| Environment | Prefix | What its messages do |
|---|---|---|
| Sandbox | lp_test_ | Captured and never delivered. Webhooks still receive events, marked as sandbox. The dashboard creates sandbox keys by default. |
| Live | lp_live_ | Delivered through Letterpier’s mail server, from a verified domain. Available once the installation can deliver mail. |
The two environments
- Sandbox
- Prefix
lp_test_- What its messages do
- Captured and never delivered. Webhooks still receive events, marked as sandbox. The dashboard creates sandbox keys by default.
- Live
- Prefix
lp_live_- What its messages do
- Delivered through Letterpier’s mail server, from a verified domain. Available once the installation can deliver mail.
A key either sends only or has full access. Give each product the smallest key it needs: most only send, and only a service that reads mail or manages settings needs full access.
| Operation | Sending only | Full access |
|---|---|---|
Send, batch-send and schedule at send time POST /emails, POST /emails/ | Yes | Yes |
List and retrieve sent messages GET /emails | No | Yes |
Reschedule and cancel PATCH /emails/, POST /emails/ | No | Yes |
Received mail and its attachments /emails/ | No | Yes, live keys only |
Domains /domains | No | Yes |
API keys /api-keys | No | Yes |
Webhooks /webhooks | No | Yes |
What each permission allows
- Send, batch-send and schedule at send time
POST /emails,POST /emails/batch - Sending only
- Yes
- Full access
- Yes
- List and retrieve sent messages
GET /emails- Sending only
- No
- Full access
- Yes
- Reschedule and cancel
PATCH /emails/,:id POST /emails/:id/ cancel - Sending only
- No
- Full access
- Yes
- Received mail and its attachments
/emails/receiving - Sending only
- No
- Full access
- Yes, live keys only
- Domains
/domains- Sending only
- No
- Full access
- Yes
- API keys
/api-keys- Sending only
- No
- Full access
- Yes
- Webhooks
/webhooks- Sending only
- No
- Full access
- Yes
A key without the permission gets 403 restricted_api_key.
A key is shown once, when you create it. Letterpier stores only its SHA-256 hash, so nobody can show it to you again, including us. The dashboard identifies keys by their first 16 characters.
If you lose a key, create a new one, switch your product to it, and revoke the old one.
Create keys in the dashboard under API keys: choose a name, the environment and the permission. Revoking a key works immediately; its next request gets 403 invalid_api_key, and it can’t be undone.
A full-access key can also manage keys through the API. Keys created this way inherit the caller’s environment.
// Full-access key. New keys inherit the caller's environment.const { data: key } = await mail.apiKeys.create({ name: 'Billing service', permission: 'sending_access',});key?.token; // Shown onceconst { data: keys } = await mail.apiKeys.list();await mail.apiKeys.remove(key!.id); // Revokes it immediatelydomain_id is rejected. apiKeys.update isn’t supported, and the list returns each active key’s id, name and created_at only.rate_limit_exceeded until the next minute starts.Adding domains (5 per minute) and verifying them (10 per minute) have their own, lower limits per project. When you retry after a 429, wait for the next minute and keep the same idempotency key.
Use keys only from your own servers, in an environment variable such as LETTERPIER_API_KEY. Never put one in a browser, a mobile app or a repository: anyone who has a key can act as your product.
If a key leaks, revoke it in the dashboard first, then replace it.