Claves de API

Las claves de API (credenciales) autentican su aplicación con la API de MailLand. Cada clave está delimitada por producto, modo, flujo, canal y, opcionalmente, restringida por dominio y dirección IP.

En el panel, cree y gestione las claves en Credentials en la barra lateral (sección Global). Las mismas operaciones están disponibles mediante la API /v1/credentials descrita a continuación.

Los ejemplos con Authorization: Bearer de esta página usan el token de acceso JWT que devuelve POST /v1/auth/login (consulte Login). Las claves de API son distintas: envíelas en la cabecera X-API-Key, nunca como token Bearer.

Formato de las clavesCopiar enlace de la sección

Todas las claves de API de MailLand siguen este formato:

ml_{mode}{product}{stream?}_{random45chars}

• ml_: prefijo para todas las claves
• Modo: p (Producción) o s (Sandbox)
• Producto: e (Envío), i (Entrante), v (Validación)
• Flujo (solo Envío): t (Transaccional) o m (Marketing)
• 45 caracteres aleatorios

Ejemplos:

ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...  → Producción Envío Transaccional
ml_sem_Xn7Kp2qR4tW9yB1cD6eF...  → Sandbox Envío Marketing
ml_pi_Mn5Jp8kL3rV6wA2xC4fG...   → Producción Entrante
ml_pv_Qw9Er3tY6uI1oP5aS8dF...   → Producción Validación

Propiedades de las credencialesCopiar enlace de la sección

Al crear una credencial, usted configura lo siguiente:

channels es una única cadena, nunca un array. Envíe "channels": "Api, Smtp" para permitir ambos canales; ["Api", "Smtp"] se rechaza con 400.

Crear una credencialCopiar enlace de la sección

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Transactional",
    "product": "Sending",
    "mode": "Production",
    "stream": "Transactional",
    "channels": "Api",
    "scope": "AllDomains",
    "rateLimitPerHour": 5000,
    "rateLimitPerDay": 50000
  }'

{
  "id": "n4k9pq2rt8mwxa",
  "name": "Production Transactional",
  "key": "ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...",
  "keyPrefix": "ml_pet_Ab3Kx9mN",
  "product": "sending",
  "mode": "production",
  "stream": "transactional",
  "channels": "api",
  "scope": "allDomains",
  "sandboxBehavior": "logOnly",
  "rateLimitPerHour": 5000,
  "rateLimitPerDay": 50000,
  "isActive": true,
  "createdAt": "2026-02-17T10:00:00Z"
}

Alcance: Restricciones de dominioCopiar enlace de la sección

De forma predeterminada, las credenciales pueden enviar desde cualquier dominio verificado en su espacio de trabajo (AllDomains). Para restringir una credencial a dominios específicos:

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing - notifications.com only",
    "product": "Sending",
    "mode": "Production",
    "stream": "Marketing",
    "channels": "Api",
    "scope": "SelectedDomains",
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

También puede actualizar las asignaciones de dominio después de la creación:

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

Restricciones de IPCopiar enlace de la sección

Restrinja una credencial a direcciones IP o rangos CIDR específicos:

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/allowed-ips \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "allowedIps": [
      { "ipAddress": "203.0.113.10", "description": "Production server" },
      { "ipAddress": "198.51.100.0/24", "description": "Office network" }
    ]
  }'

Cuando se configuran restricciones de IP, las solicitudes de API desde IPs no listadas devuelven 403 IP_NOT_ALLOWED.

Configuración de canalesCopiar enlace de la sección

El campo channels controla dónde puede autenticarse una credencial:

Para usar una credencial con la retransmisión SMTP, asegúrese de que Smtp esté incluido en los canales. Al autenticarse mediante SMTP, use cualquier nombre de usuario y la clave de API como contraseña.

Rotación de clavesCopiar enlace de la sección

Rote la clave de API de una credencial sin tiempo de inactividad utilizando un período de gracia:

curl -X POST https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/rotate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "gracePeriodHours": 24
  }'

{
  "key": "ml_pet_Yn8Lq3rS5uW0zA4bC7dE...",
  "oldKeyExpiresAt": "2026-02-18T10:00:00Z"
}

Durante el período de gracia (predeterminado: 24 horas), tanto la clave antigua como la nueva son válidas. Una vez transcurrido el período de gracia, la clave antigua deja de funcionar.

Modo SandboxCopiar enlace de la sección

«Sandbox» significa dos cosas distintas que se combinan:

1. Credenciales Sandbox (mode: Sandbox). Para desarrollo, CI/CD y staging. Lo que ocurre con un envío depende del sandboxBehavior de la credencial:

• LogOnly (predeterminado): la solicitud se valida y se responde 202, pero no se entrega nada ni se crea ningún mensaje. La respuesta incluye isSandboxed: true, sandboxReason: "credential_sandbox_mode" y messageIds vacío.
• AllowListOnly: los destinatarios que coinciden con la lista de permitidos de sandbox de su espacio de trabajo reciben el correo de verdad; los demás se devuelven en rejectedRecipients con el motivo recipient_not_in_sandbox_allowlist. Si ningún destinatario está permitido, la respuesta sigue siendo 202 con acceptedRecipients: [] y sandboxReason: "all_recipients_not_in_sandbox_allowlist".

Por SMTP, una credencial sandbox nunca entrega: el mensaje se acepta y se registra pero no se envía, sea cual sea su sandboxBehavior.

2. Espacios de trabajo Sandbox. Un espacio de trabajo nuevo empieza en el nivel de verificación Sandbox (vea Espacios de trabajo). Hasta que se verifique, el envío queda limitado a destinatarios de la lista de permitidos, incluso con una credencial Production. Cualquier otro destinatario se rechaza con 429 SENDING_BLOCKED («Recipient '…' is not in sandbox allowlist. Add to allowlist or complete verification.»).

Gestione la lista de permitidos en el panel, en Configuración → Sandbox Allow List. Una entrada es una dirección ([email protected]) o un dominio completo (*@example.com). La misma lista está disponible con GET /v1/account/settings/sandbox-allowlist, POST /v1/account/settings/sandbox-allowlist, DELETE /v1/account/settings/sandbox-allowlist/{email} (token bearer del panel; POST acepta email y description opcional).

Gestión de credencialesCopiar enlace de la sección

Listar credencialesCopiar enlace de la sección

curl "https://api.mail.land/v1/credentials?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Filtrar por producto o modo:

curl "https://api.mail.land/v1/credentials?product=Sending&mode=Production" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Actualizar una credencialCopiar enlace de la sección

curl -X PATCH https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "rateLimitPerHour": 10000,
    "isActive": false
  }'

Todos los campos son opcionales: incluya solo los que desee cambiar.

Eliminar una credencialCopiar enlace de la sección

curl -X DELETE https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Devuelve 204 No Content en caso de éxito. Las credenciales eliminadas dejan de autenticarse inmediatamente. La eliminación revoca la clave: la credencial sigue apareciendo en GET /v1/credentials con isActive: false.

Límites de tasaCopiar enlace de la sección

Cada credencial tiene sus propios límites de tasa, independientes de otras credenciales:

Cuando se supera un límite de tasa, la API devuelve 429 con encabezados X-RateLimit-*:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708171800
Retry-After: 45

Próximos pasosCopiar enlace de la sección

• Inicio rápido: envíe su primer correo electrónico
• API REST: referencia completa de la API de envío
• Retransmisión SMTP: autentíquese con su clave de API mediante SMTP