API keys & security
Separate credentials, scope sending domains, and rotate or revoke keys safely.
1. Two Bearer credentials
A user session token manages domains, api-keys and webhooks. An API Key is used for /v1/mail and the SMTP password. It is not an account password, session token or locale cookie. GET /v1/apikey/verify checks a key, not domain verification or available package quota.
2. Create and save
After email verification, use POST /api-keys with a non-empty name and optional numeric domain_id. The full key appears only in the 201 creation response. Store it in a server-side secret manager, never logs, screenshots or frontend code. Lists cannot recover the plaintext.
| Field / setting | Type / status | Description |
|---|---|---|
| name | string | Non-empty at creation |
| domain_id | uint64 | Optional domain ID at creation |
| key | string | Full key, creation response only |
| id / key_prefix / status | uint64 / string | List metadata; key_prefix cannot authenticate |
| allowed_domain_id / last_used_at | uint64 / time | Optional metadata, not guaranteed null fields |
curl -X POST "${SMTPDOG_API_ORIGIN}/api-keys" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}" \
-H "Content-Type: application/json" \
--data '{"name":"Server integration","domain_id":123}'
curl -X GET "${SMTPDOG_API_ORIGIN}/api-keys" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"
curl -X DELETE "${SMTPDOG_API_ORIGIN}/api-keys/${SMTPDOG_KEY_ID}" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"3. Scope sending domains
Omitting domain_id allows sending from the account’s verified domains; specifying it limits sending to that domain. Ownership is checked at creation and verified status at sending. Key expiry, roles and editing a key’s scope are not supported. Scope never replaces domain ownership verification or abuse checks.
4. Rotate and revoke
Rotate by creating a new key, updating your service configuration, confirming the switch, then revoking the old key with DELETE /api-keys/{id}. Revocation returns 204 without a body; new requests cannot use the revoked key. There is no in-place rotation or plaintext recovery endpoint. If you used a session token by mistake, check the required authentication before retrying.