Autenticación

Cada petición a la API de Emailit debe llevar una credencial en la cabecera Authorization. Esta página explica los dos tipos de credenciales (claves de API y tokens de acceso OAuth), qué puede hacer cada permiso y todos los errores de autenticación que puedes recibir.

Claves de API

Una clave de API pertenece a un espacio de trabajo, y cada petición que haces con ella actúa sobre ese espacio de trabajo. Las claves tienen este aspecto:

secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG

Es decir, secret_ seguido de 32 letras y dígitos. Las claves creadas antes del formato secret_ no tienen prefijo y siguen funcionando.

Crea claves en el panel, en Email API›API Keys, o con Crear una clave de API. El secreto se muestra una sola vez, al crear o regenerar la clave, así que guárdalo enseguida. Para gestionarlas, consulta Claves de API.

Las mismas claves sirven como contraseña SMTP del SMTP relay.

Enviar la clave con cada petición

Usa el esquema Bearer en la cabecera Authorization. La API no acepta claves en la cadena de consulta ni en el cuerpo de la petición.

curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();

import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()

Los SDK añaden esta cabecera por ti cuando pasas la clave al cliente.

Permisos

Cada clave tiene uno de dos permisos. Lo eliges al crear la clave y no puedes cambiarlo después.

Una clave sending puede llamar a estos endpoints y a ningún otro:

Para leer emails (listarlos, obtenerlos, y consultar el mensaje en bruto, el cuerpo, los metadatos, los adjuntos y el estado) necesitas una clave full. Cuando una clave sending llama a cualquier otro endpoint, la API devuelve 403 con Permission denied: full (o Permission denied: read en los endpoints de lectura de emails).

Todos los endpoints indica el permiso de cada endpoint.

Limitar una clave a un dominio

Una clave sending también puede limitarse a un dominio de envío. Pasa el ID del dominio como sending_domain_id al crear la clave. Una clave limitada solo puede enviar desde direcciones de ese dominio. Cualquier otro dominio en from devuelve 403:

{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}

La limitación a un dominio solo se aplica a las claves sending. Una clave full siempre tiene acceso a todos los dominios del espacio de trabajo.

Tokens de acceso OAuth

Las aplicaciones que actúan en nombre de un usuario de Emailit, como los clientes MCP y las integraciones de terceros, no piden una clave de API. En su lugar usan OAuth 2.1: el usuario inicia sesión en Emailit, elige los espacios de trabajo que puede usar la aplicación (todos o solo algunos) y aprueba el permiso sending o full, y la aplicación recibe un token de acceso. El usuario puede cambiar o revocar ese acceso en Connected apps.

Envía los tokens de acceso en la misma cabecera que las claves de API:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

Un token de acceso es válido durante 15 minutos y actúa sobre el espacio de trabajo por defecto de la autorización, con el permiso concedido y el rol del usuario en ese espacio de trabajo. Las aplicaciones lo renuevan con el token de actualización. Para crear una, consulta Aplicaciones OAuth.

Errores de autenticación

La autenticación se comprueba antes que nada, así que estos errores pueden llegar desde cualquier endpoint.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}

{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}

Espacios de trabajo sin verificar

Los espacios de trabajo nuevos empiezan sin verificar. Hasta que Emailit aprueba el acceso de producción, la API solo envía a las direcciones de email de las cuentas de los miembros del espacio de trabajo. Enviar, reintentar o reenviar a cualquier otra dirección devuelve 403 con el código unverified_workspace_recipient y la lista blocked_recipients, y las campañas no se pueden enviar en absoluto. Tus claves de API funcionan con normalidad para todo lo demás.

Mantener tus claves en secreto

Una clave de API da acceso a tu espacio de trabajo, así que trátala como una contraseña.

• Llama a la API solo desde tu servidor. No pongas nunca una clave en el JavaScript del navegador, en una aplicación móvil ni en ningún otro código que se ejecute en el dispositivo de otra persona.
• No guardes las claves en el control de versiones. Cárgalas desde variables de entorno o desde un gestor de secretos.
• Crea una clave por aplicación y entorno, y ponle un nombre que indique dónde se usa, para poder revocar una sin afectar a las demás.
• Da a cada clave el mínimo acceso que necesite: una clave sending limitada a un dominio basta para la mayoría de las aplicaciones.
• Comprueba last_used_at en Listar claves de API y elimina las claves que ya no uses.
• Si se filtra una clave, regenérala o elimínala de inmediato. El secreto anterior deja de funcionar al instante.

Ver también