API keys
API keys authenticate every programmatic request: sending, and the management endpoints.
Create a key
Open API keys → Create key, name it (so you recognise it later, e.g. the service that will use it), and copy it once. Keys are stored hashed and shown a single time; if you lose it, revoke and create a new one.
Treat keys like passwords. Store them in your platform's secret manager, never in source control or client-side code.
Use it
Send the key as a Bearer token:
Authorization: Bearer mh_live_xxxxxxxxThe SDKs and the curl examples throughout these docs read it from an environment variable such as MAILHUSET_API_KEY.
Live and test keys
Each key is either live (mh_live_…) or test (mh_test_…), chosen when you create it. A test key runs in sandbox mode: requests are validated and recorded in your message log exactly as normal, but the email is never actually sent — so it never reaches a real inbox, counts against your quota, or bills.
Use a test key to build and exercise your integration end to end without side effects. Switch to a live key when you're ready to send for real. A whole project can also be created in sandbox mode, which forces every key in it to behave this way.
Key scopes
Restrict what a key can do with scopes:
email:send— send email onlyemail:read— read messages, stats and events onlymanage— everything else (domains, keys, webhooks, suppressions)
A key with no scopes has full access (the default, for back-compatibility). Give each integration the narrowest set it needs.
Scope
Keys are scoped to their project, so a staging key can't touch production. Create separate keys per environment and per integration, so you can revoke one without disrupting the others.
Rotate & revoke
Revoke a key from the same page the moment it might be exposed; requests with it fail immediately. Rotating regularly is good hygiene: create the new key, deploy it, then revoke the old one.
Need help? Email support@mailhuset.com.