Domain access per API key

Every API key has a domain access setting (domain_access) that determines which verified domains on your account it can send from. There are two modes:

all — the key can send from any verified domain on your account, today and in the future. You don’t authorize anything by hand: if you verify a new domain, every key in all mode can use it right away.
restricted — the key can only send from the specific domains you choose (allowed_from_domains). Least-privilege: useful for a key handed to a third-party vendor, a staging environment, or any credential you want to explicitly limit.

This follows the same model as SendGrid, Postmark, and Resend: a verified domain is owned by the account, not by an individual key — the API key encodes permissions, not sender identity.

Create a key with access to all domains (default)

curl -X POST https://api.mailerdash.com/v1/client/keys \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "production-app"}'

Since no domain_access was sent, the key defaults to all:

{
  "id": "key_abc123",
  "label": "production-app",
  "token": "md_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "domain_access": "all",
  "allowed_from_domains": []
}

Create a key restricted to specific domains

Pass domain_access: "restricted" along with the list of domains the key will be allowed to use:

curl -X POST https://api.mailerdash.com/v1/client/keys \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "staging-app",
    "domain_access": "restricted",
    "allowed_from_domains": ["staging.tuempresa.com"]
  }'

{
  "id": "key_def456",
  "label": "staging-app",
  "token": "md_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "domain_access": "restricted",
  "allowed_from_domains": ["staging.tuempresa.com"]
}

Domains in allowed_from_domains must belong to your account. If you haven’t verified one yet, follow the verify a domain guide — an unverified domain can never send, no matter what domain_access the key attempting it has.

Change the scope of an existing key

PATCH /v1/client/keys/{id}/domain-access

Body: { "domain_access": "restricted" } or { "domain_access": "all" }.

curl -X PATCH https://api.mailerdash.com/v1/client/keys/key_abc123/domain-access \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain_access": "restricted"}'

{
  "id": "key_abc123",
  "domain_access": "restricted"
}

What happens in each direction:

all → restricted: the domains your account has verified at that moment become explicitly authorized for the key — no in-flight sends are interrupted. From then on, any new domain you verify is not automatically added to this key; you have to authorize it by hand.
restricted → all: the key starts inheriting every verified domain on the account, including ones you verify in the future. Its existing explicit authorizations aren’t deleted, but they stop being necessary.

This change doesn’t require a password — like creating a key, it’s a low-friction operation — and it’s recorded in your account’s audit log.

Without a verified domain, no key can send

Scope (all or restricted) never replaces DNS verification: if a domain isn’t verified at the account level, no key can send from it, regardless of its domain_access. Attempting to do so returns 403 with code: "domain_unauthorized" — see the error reference.

API reference: Platform — Keys