Alcance de dominios por API key

Cada API key tiene un alcance de dominios (domain_access) que determina desde qué dominios verificados de tu cuenta puede enviar. Hay dos modos:

all — la key puede enviar desde cualquier dominio verificado de tu cuenta, hoy y a futuro. No autorizas nada a mano: si verificas un dominio nuevo, todas tus keys en modo all pueden usarlo de inmediato.
restricted — la key solo puede enviar desde los dominios específicos que elijas (allowed_from_domains). Least-privilege: útil para una key de un proveedor externo, un ambiente de staging, o cualquier credencial que quieras limitar explícitamente.

Este modelo sigue el mismo estándar que SendGrid, Postmark y Resend: el dominio verificado es propiedad de la cuenta, no de una key individual — la API key codifica permisos, no identidad de remitente.

Crear una key con acceso a todos los dominios (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"}'

Como no se envía domain_access, la key queda en all:

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

Crear una key restringida a dominios específicos

Pasa domain_access: "restricted" junto con la lista de dominios que la key podrá usar:

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"]
}

Los dominios de allowed_from_domains deben pertenecer a tu cuenta. Si todavía no verificaste alguno, sigue la guía para verificar un dominio — un dominio sin verificar nunca puede enviar, sin importar el domain_access de la key que lo intente.

Cambiar el alcance de una key existente

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

Body: { "domain_access": "restricted" } o { "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"
}

Qué pasa en cada dirección:

all → restricted: los dominios verificados que tu cuenta tiene en ese momento quedan autorizados explícitamente para la key — ningún envío en curso se interrumpe. De ahí en adelante, cualquier dominio nuevo que verifiques no se agrega automáticamente a esta key; tienes que autorizarlo a mano.
restricted → all: la key pasa a heredar todos los dominios verificados de la cuenta, incluidos los que verifiques a futuro. Las autorizaciones explícitas que tenía no se borran, pero dejan de ser necesarias.

Este cambio no pide contraseña — igual que crear una key, es una operación de baja fricción — y queda registrado en el log de auditoría de tu cuenta.

Sin dominio verificado, ninguna key puede enviar

El alcance (all o restricted) nunca reemplaza la verificación DNS: si un dominio no está verificado a nivel de cuenta, ninguna key puede enviar desde él, sin importar su domain_access. Intentarlo devuelve 403 con code: "domain_unauthorized" — ver la referencia de errores.

Referencia API: Plataforma — Keys