Authentication

API keys

All requests to the Sendr API must be authenticated with an API key. Create and manage keys in the Sendr dashboard under API Keys.

Keys are prefixed to indicate their mode:

Prefix	Mode	Description
sndr_live_...	Live	Real email delivery
sndr_test_...	Test	Captures emails to Test Inbox, no real delivery

Sending requests

Pass your API key as a Bearer token in the Authorization header:

Authorization: Bearer sndr_live_your_api_key_here

Example:

curl https://api.sendr.dev/v1/emails \
  -H "Authorization: Bearer sndr_live_your_api_key_here"

API key scopes

Every key has one of three scopes. Scopes are hierarchical — a higher-privilege scope satisfies all lower requirements.

Scope	Level	Permissions
full_access	3	Create/delete resources, send emails, read data
sending_access	2	Send emails, read email data
read_only	1	Read data only, no sending or mutations

Scope hierarchy: full_access > sending_access > read_only

A key with full_access can call any endpoint. A key with sending_access can send emails but cannot create domains or manage webhooks. A read_only key can only fetch data.

Choosing the right scope

• Backend servers sending transactional email — use sending_access
• Admin tools or CI/CD — use full_access
• Analytics dashboards or monitoring — use read_only
• Client-side apps — avoid embedding API keys; use a backend proxy

Creating API keys

import { Sendr } from "sendr";

const sendr = new Sendr(process.env.SENDR_ADMIN_KEY!);

// The key value is only returned once — store it immediately
const { key } = await sendr.apiKeys.create({
  name: "Production Sender",
  scope: "sending_access",
});

console.log(key); // sndr_live_abc123... — save this now

Via the REST API:

curl -X POST https://api.sendr.dev/v1/api-keys \
  -H "Authorization: Bearer $SENDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Sender", "scope": "sending_access"}'

The raw key value is only returned once at creation time. After that, only the key ID and name are stored. If you lose a key, delete it and create a new one.

Plan limits on API keys

Plan	API keys
Free	2
Pro	10
Business	50
Enterprise	Unlimited

Test mode keys

Test-mode keys (sndr_test_...) are ideal during development:

• Bypass domain verification — you can send from any from address
• Emails are captured to the Test Inbox (visible in the dashboard) instead of being delivered
• Useful in CI/CD or staging environments

// Create a test-mode key
const { key } = await sendr.apiKeys.create({
  name: "CI Test Key",
  scope: "sending_access",
  mode: "test",
});

Key expiration

API keys can be set to expire. Requests with an expired key return 401 expired_key.

Security best practices

1. Never expose API keys in client-side code. Keys in browser JavaScript can be extracted by anyone. Use a server-side proxy.
2. Use the minimum necessary scope. If you only need to send emails, use sending_access — not full_access.
3. Rotate keys regularly. Delete and recreate keys on a schedule or when team members leave.
4. Store keys in environment variables, not in source code or configuration files.
5. Use test-mode keys in development and staging — they can't cause real email delivery.
6. Monitor key usage in the dashboard to detect unexpected activity.

Error responses

Code	Status	Cause
unauthorized	401	Missing or invalid API key
expired_key	401	API key has expired
insufficient_scope	403	Key scope is too low for this endpoint

See Error Codes for the full list.