Authentication
Every v1 endpoint requires an API key. There are two ways to send it.
Bearer token (recommended)
Send your key in the Authorization header:
curl https://api.mailfloss.com/v1/organization \
-H "Authorization: Bearer YOUR_API_KEY"This is the preferred scheme for all new integrations. It keeps your key out of URLs, request logs, and browser history.
Legacy api_key query parameter (deprecated)
Prefer the Bearer header for every integration. The api_key query parameter is deprecated, and the original legacy API that relied on it sunsets June 1, 2027. Switching to Bearer is a one-line change (below).
Older integrations pass the key as a query parameter:
curl "https://api.mailfloss.com/v1/organization?api_key=YOUR_API_KEY"This still works on v1, but it's soft-deprecated. Requests authenticated this way receive a Deprecation: true response header. Query parameters are easy to leak through server logs, proxies, and referrer headers.
Migrating to Bearer — move the key out of the query string and into the Authorization header:
# Before — legacy api_key query parameter
curl "https://api.mailfloss.com/v1/organization?api_key=YOUR_API_KEY"
# After — Bearer token (recommended)
curl https://api.mailfloss.com/v1/organization \
-H "Authorization: Bearer YOUR_API_KEY"If you supply both a Bearer token and an api_key parameter on the same request, the Bearer token wins.
Getting and managing your key
Your API key is in the mailfloss dashboard under Settings → API. Keys are scoped to your organization.
Treat the key as a secret:
- Keep it server-side. Never ship it in client-side JavaScript, mobile apps, or anything a user can inspect.
- Don't commit it to source control. Load it from an environment variable or a secrets manager.
- Rotate it if you suspect exposure.
Key formats
Today's full-scope keys are prefixed mf_live_. The API uses the key prefix to route to its validation strategy, which lets future key types arrive without any protocol change:
Prefix | Meaning |
|---|---|
mf_live_* | Full-scope API key (current) |
mf_rk_* | Restricted (scoped) key — coming in a future release |
mf_oauth_* | OAuth-issued token — coming in a future release |
You don't need to do anything to prepare for scoped keys or OAuth; they'll be additive.
Authentication errors
A missing or rejected key returns a 401 with an authentication_error:
{
"error": {
"code": "invalid_api_key",
"message": "The provided API key is invalid.",
"type": "authentication_error",
"request_id": "req_a1b2c3"
}
}Common codes: missing_api_key (no key supplied) and invalid_api_key (key rejected). See the Errors guide for the full model.