Authentication

API keys

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

Keys are prefixed to indicate their mode:

Prefix	Mode	Description
sn_live_...	Live	Real email delivery
sn_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 sn_live_your_api_key_here

Example:

curl https://api.sendry.online/v1/emails \
  -H "Authorization: Bearer sn_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 { Sendry } from "sendry-sdk";

const sendry = new Sendry(process.env.SENDRY_ADMIN_KEY!);

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

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

Via the REST API:

curl -X POST https://api.sendry.online/v1/api-keys \
  -H "Authorization: Bearer $SENDRY_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 (sn_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 sendry.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.

Transferring keys between organizations

POST /v1/api-keys/:id/transfer

Move an API key to another organization. Requires full_access scope and a dashboard session (not an API key); the signed-in user must own or be an admin of the target organization.

The transfer rotates the secret server-side, so the previous holder can no longer use the old value. The fresh key string is returned exactly once in the response.

Request body

Field	Type	Required	Description
target_org_id	string	Yes	ID of the organization the key should be moved to.

Response

{
  "id": "key_...",
  "name": "...",
  "scope": "full_access",
  "mode": "live",
  "key": "sn_live_NEW_VALUE",
  "created_at": "..."
}

Update any clients with the new key string before continuing to send.

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.