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-keysPOST
/v1/api-keysDELETE
/v1/api-keys/:idnoteSigning 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.