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_xxxxxxxx

The 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 only
• email:read: read messages, stats and events only
• manage: 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.

SMTP credentials

An SMTP credential is a key with only the smtp:send scope. It is the password for the SMTP relay and can do nothing else: it cannot call the API, and an ordinary API key, even one with full access, cannot log in to the relay. Create SMTP credentials on the dashboard's SMTP relay page rather than here; they are listed with your keys, marked SMTP, and are revoked the same way.

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.