Claves de API

Las claves de API autentican tus peticiones a la API REST, tus conexiones SMTP y las sesiones con clave de API en el servidor MCP. En esta página se explican los dos permisos que puede tener una clave, cómo crear y gestionar claves y cómo guardarlas y rotarlas de forma segura.

Cómo funcionan las claves de API

• Cada clave pertenece a un espacio de trabajo. Todo lo que haces con ella ocurre en ese espacio de trabajo.
• Las claves nuevas empiezan por secret_ seguido de 32 letras y dígitos, por ejemplo secret_••••••••. Las claves creadas antes de que se introdujera el prefijo siguen funcionando.
• Emailit muestra la clave completa una sola vez, al crearla o regenerarla. Cópiala en ese momento; no podrás volver a verla.
• La clave se envía como token bearer: Authorization: Bearer secret_…. En SMTP, la clave es la contraseña.

Permisos

Cada clave tiene uno de estos dos permisos. El permiso se elige al crear la clave.

Una clave Sending Only que llama a cualquier otro endpoint recibe 403 con un mensaje como Permission denied: read. Usa claves Full Access para las tareas internas que gestionan recursos y claves Sending Only para todo lo que solo necesita enviar.

Limitar una clave a un dominio

Al crear una clave Sending Only, puedes elegir un dominio de envío verificado. Así, la clave solo puede enviar desde direcciones de ese dominio:

• Por la API, enviar desde otro dominio devuelve 403 con "error": "Domain not authorized".
• Por SMTP, el mensaje se rechaza después de DATA con 530 API key is restricted to sending domain: ….

Las claves limitadas son una buena opción para credenciales por aplicación o por cliente, y para las claves que tienes que dar a software de terceros, como el plugin de un CMS.

Antes de empezar

• Necesitas el rol Admin en el espacio de trabajo para crear, editar, regenerar o eliminar claves. Los miembros pueden ver la lista de claves, pero no modificarla. Consulta Miembros y roles.
• Para enviar con una clave, necesitas al menos un dominio de envío verificado.

Crear una clave de API

curl https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-web",
    "scope": "sending",
    "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6"
  }'

{
  "object": "api_key",
  "id": "key_4F2kN8sQwE1rT6yU3iO9pA7sD5f",
  "name": "production-web",
  "scope": "sending",
  "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6",
  "last_used_at": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-01T09:30:00.000Z",
  "key": "secret_••••••••••••••••••••••••••••••••"
}

Usar la clave

Pasa la clave en la cabecera Authorization de cada petición a la API:

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order has shipped",
    "text": "Your order #1042 is on its way."
  }'

Para enviar por SMTP, usa la clave como contraseña:

Para ver todas las opciones, consulta Configuración SMTP.

Gestionar las claves

Abre una clave desde Email API›API Keys para ver su permiso, su dominio, la fecha Created, la hora Last used y la configuración SMTP que debes usar con ella.

Last used se actualiza cada vez que la clave autentica una petición a la API o un inicio de sesión SMTP. Una clave que nunca se ha usado muestra Never. En la API, los endpoints que reciben el ID de una clave también aceptan su nombre.

Guardar las claves de forma segura

• Mantén las claves en el servidor. No pongas nunca una clave en el JavaScript del navegador, en una app móvil, en un repositorio público ni en un ticket de soporte. Cualquiera que tenga la clave puede enviar emails en tu nombre y gastar tus créditos.
• Usa variables de entorno o un gestor de secretos. Carga la clave en tiempo de ejecución, por ejemplo desde EMAILIT_API_KEY. Añade los archivos .env a .gitignore.
• Da a cada aplicación y a cada entorno su propia clave. Con claves separadas para producción, preproducción y cada herramienta de terceros, es fácil ver quién envió qué y revocar una sin tocar las demás.
• Usa el permiso más limitado. Si una aplicación solo envía emails, dale una clave Sending Only, limitada a su dominio siempre que sea posible.
• Vigila el uso. Email API›Logs muestra las peticiones a la API y SMTP por clave, y puedes filtrar Email API›Emails por clave de API. Consulta Registros de peticiones.
• Actúa rápido ante una filtración. Si una clave queda expuesta, regenérala o elimínala de inmediato y después revisa los registros en busca de envíos inesperados.

Rotar una clave sin interrupciones

Regenerar una clave anula el secreto anterior al instante, así que hazlo solo cuando una clave esté comprometida. Para una rotación planificada, usa la clave antigua y la nueva en paralelo:

1. Crea una clave nueva. Añade una clave con el mismo permiso y la misma limitación de dominio que la que vas a sustituir. Ponle un nombre que indique la fecha, como production-web-2026-10.

2. Despliega la clave nueva. Actualiza el secreto en tu gestor de secretos o en tu entorno y llévalo a todos los servidores, workers y tareas programadas que usan la clave antigua.

3. Confirma el cambio. Abre la clave nueva y comprueba que Last used es reciente. En Email API›Logs, filtra por la clave antigua y comprueba que ya no llegan peticiones.

4. Elimina la clave antigua. Cuando la hora Last used de la clave antigua deje de cambiar, elimínala.

Solución de problemas

Ver también