API keys

The Email API authenticates every request with a single header:

Api-Key: rs_eml_a8K2pX7dL3qVnWj4mC9bRzT1yU6sH0eF

Keys are scoped to a single email service — they cannot read or send through any other service in your workspace.

Key format

Every key has the same shape:

rs_eml_<32 random characters>

• rs_ — Runsite namespace.
• eml_ — service prefix (Email).
• <32 chars> — the secret material, drawn from [A-Za-z0-9].

Total length: 40 characters. The first 8 characters of the random part (e.g. a8K2pX7d) are stored as a non-secret lookup prefix and used in the dashboard list view (e.g. rs_eml_a8K2pX7d…). The full key is hashed at rest — the dashboard cannot show it again after creation.

Creating a key

1. Open the email service.
2. Switch to the API Keys tab.
3. Click Create Key.
4. Give it a name (recommended — e.g. production, staging, ci-cd, localdev).
5. Confirm.

The dashboard shows the full key one time only in a copy-pasteable box, plus a ready-to-paste cURL / Python / JavaScript snippet. Save it somewhere safe (a secret manager, your service env vars) immediately — there is no way to retrieve it later. If you lose it, revoke and create a new one.

Storing keys safely

The key is a password

Anyone holding the key can send mail through your service, see message status and statistics. Treat it like a database password — no second factor, no IP allowlist by default.

Recommended practice:

• Store the key in your environment variables, never in source control.
• For a Runsite Web Service, add it under Settings → Environment as EMAIL_API_KEY (or whatever name you like). Read it in code with process.env.EMAIL_API_KEY / os.environ["EMAIL_API_KEY"].
• One key per environment (dev / staging / prod) so each can be rotated independently.
• Don’t ship keys to the browser. The Email API is server-to-server. From a SPA, call your own backend; the backend holds the key and forwards the request.

Listing and revoking keys

The API Keys tab shows every key for the service:

Column	Notes
Key prefix	The lookup prefix (e.g. rs_eml_a8K2pX7d…). The full key is never shown again.
Name	Whatever you named it at creation.
Last used	Timestamp of the most recent successful request, or Never.
Status	Active or Revoked.

To revoke, click the trash icon on the row. Revocation is immediate — any client still using the key gets 401 Unauthorized on the next call.

Rotation

There’s no automatic expiry; rotate manually with zero downtime:

1. Create a new key on the service.
2. Update the credential in your service’s environment / secret manager and redeploy. Both keys are valid right now.
3. Watch the Last used timestamp on the old key for a day or two — once it’s clearly idle, revoke it.

A good cadence is every 90 days for production keys, plus an immediate rotation any time someone leaves the team or you suspect a leak.

Common errors

Status	Body	What it means
401	Missing API key	The Api-Key: header was absent.
401	Invalid API key format	The header value didn’t start with rs_eml_.
401	Invalid API key	The header value matched the format but didn’t match any active key for any service.
403	Service inactive	The key is valid, but its email service was deleted / suspended.

Always log the response body when troubleshooting — the message tells you which of these you hit.