Authentication
The REST API uses API keys. Each key belongs to one newsletter and can be revoked at any time. Keys are shown once, when you create them.
Create a key
- Open API keys in the dashboard.
- Choose a name you will recognise later.
- Copy the key. It is not shown again.
Send the key
Pass the key as a bearer token in the Authorization header. Never put a key in a query string, a URL, or client-side code.
curl https://app.stalkmail.com/api/v1/newsletter \\
-H "Authorization: Bearer $STALKMAIL_API_KEY"What a key can do
A key acts only on the newsletter it was created for. It can read the newsletter and its subscriber counts, and create, update or delete that newsletter's subscribers. Finer-grained scopes are planned before general availability.
Revoking and rotating
Revoke a key from the same page you created it. Revocation is immediate. If a key may have leaked, revoke it first and create a replacement after. Every action is logged with the key that made it.
Rate limits
Requests are limited per key. When you hit the limit the API returns 429 with a Retry-After header. Back off and retry; do not open more keys to work around it.