Getting started

Authentication

Bearer API keys, live vs. test environments, and how requests are scoped.

Every request authenticates with an API key in the Authorization header as a Bearer token:

header

Authorization: Bearer rm_live_8f2a…

The dashboard also accepts your logged-in session for its own server-side calls, but for the API and SDK you always use a key. Only the SHA-256 hash of a key is stored — if you lose it, roll a new one; it can't be recovered.

Live vs. test

`rm_live_…`key	Sends real email. Counts against your plan.
`rm_test_…`key	Runs in the sandbox: accepted, fully processed, but never delivered and never billed. Perfect for CI.

A key belongs to one workspace, so the environment (live/test) is the workspace it was created in — you don't pass an environment flag.

Managing keys

GET/v1/api-keysList your keys (prefix + metadata; never the secret).

POST/v1/api-keysMint a new key — the secret is returned once.

DELETE/v1/api-keys/:idRevoke a key immediately.

noteSigning up mints no key automatically — the dashboard runs on your session. Create keys on demand under Developers → API keys when you're ready to integrate.

Scoping to a client (sub-tenant)

If you send on behalf of your own customers, add the X-Rootmail-Subtenant header (or mail.withSubTenant(id) in the SDK) to scope a request to one client's domain, contacts, and reputation. See Client domains.