Authentication

Every request carries a bearer token:

Authorization: Bearer ms_...

There is no other authentication scheme, and no unauthenticated endpoint.

Two kinds of key

Use SENDING for anything that lives in an application. A key deployed to a server is a key that can leak, and a leaked SENDING key can send mail from your domain — bad, but recoverable. A leaked FULL key can mint more keys, delete your domains and read your contacts.

Restricting a key to one domain

A key can be tied to a single domain, in which case it can only send from that domain and can only see that domain:

curl -X POST https://app.mailstein.com/api/v1/apiKeys \
  -H "Authorization: Bearer $MAILSTEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"marketing-app","permission":"SENDING","domainId":1}'

Worth doing if you run several brands from one account: it means a mistake in one application cannot send as another.

Rotating a key

There is no rotate operation, deliberately. Create the new key, deploy it, confirm traffic has moved, then delete the old one. A rotate-in-place would invalidate the old key at a moment you do not control.

curl -X DELETE https://app.mailstein.com/api/v1/apiKeys/42 \
  -H "Authorization: Bearer $MAILSTEIN_API_KEY"

Deletion takes effect immediately. Anything still using that key starts getting 401 on its next request.

What is stored

The key is hashed with scrypt. What is kept in readable form is the first six characters and the last three — enough to tell two keys apart in a list, not enough to use one. Nobody at mailstein can read your key back to you, which is why losing it means making a new one.