Descripción general para desarrolladores

En esta página se reúnen las convenciones que necesitas conocer antes de escribir código para Emailit: dónde está la API, cómo se autentican las peticiones, cómo se identifican los objetos y cómo funcionan los errores, la paginación y los límites de velocidad. Cada sección enlaza con la referencia detallada.

Formas de integración

¿No sabes si usar la API o SMTP? Lee API o SMTP.

URL base y control de versiones

Todos los endpoints REST están bajo una única URL base:

https://api.emailit.com/v2

v2 es la versión actual y la única documentada. La antigua API v1 está obsoleta; consulta Control de versiones.

Autenticación

Envía una clave de API como token bearer en la cabecera Authorization de cada petición:

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

• Las claves de API empiezan por secret_. Las claves antiguas sin el prefijo siguen funcionando.
• Cada clave pertenece a un espacio de trabajo y tiene un permiso: Full Access (full) puede llamar a todos los endpoints y Sending Only (sending) solo puede enviar y gestionar los envíos. Consulta Claves de API.
• Los tokens de acceso OAuth emitidos para aplicaciones OAuth se aceptan en la misma cabecera.
• Si falta la clave, se devuelve 401 con API key required; una clave desconocida devuelve 401 con Invalid API key, y un espacio de trabajo suspendido devuelve 403 con Workspace is suspended.

No llames nunca a la API con tu clave desde un navegador o una app móvil. Mantenla en tu servidor. Más detalles: Autenticación.

ID y prefijos

Cada objeto tiene un ID de tipo cadena con un prefijo que indica el tipo, así que puedes saber de un vistazo a qué se refiere un ID.

Los dominios creados antes del cambio a los ID dom_ pueden tener todavía ID sd_ o sed_.

Algunos endpoints también aceptan un identificador legible en lugar del ID: un nombre para las claves de API, los dominios, los webhooks, las campañas y las listas de contactos, y una dirección de email para los contactos y las direcciones bloqueadas. Los emails, las plantillas y los eventos solo se buscan por ID.

Peticiones y respuestas

• JSON de entrada, JSON de salida. Envía los cuerpos de las peticiones en JSON con Content-Type: application/json. Un JSON mal formado devuelve 400 con Invalid JSON in request body. El cuerpo de una petición puede ocupar hasta 50 MB, y el mensaje MIME final de un email, hasta 40 MB.
• Errores. La mayoría de los errores devuelven {"statusCode", "error", "message"}. Los errores de validación añaden un array details y los errores de envío devuelven validation_errors. Las funciones que dependen del plan devuelven 403 con "error": "plan_required". Consulta Errores.
• Paginación. Los endpoints de listado reciben page y limit (de 1 a 100) y devuelven data, next_page_url y previous_page_url. Las plantillas y las automatizaciones usan page y per_page. Consulta Paginación.
• Filtrado y ordenación. Filtra con field.condition=value, combina filtros con match=all o match=or y ordena con order y direction. Por ejemplo, GET /v2/emails?status.exact=bounced&order=created_at&direction=desc. Consulta Filtrado y ordenación.
• Idempotencia. Envía una cabecera Idempotency-Key en POST /emails y POST /emails/:id/forward para que los reintentos sean seguros. Emailit repite la primera respuesta durante 24 horas. Consulta Idempotencia.
• Límites de velocidad. El envío está limitado por espacio de trabajo, por defecto a 2 emails por segundo y 5000 emails al día, compartidos entre la API y SMTP. Las respuestas incluyen las cabeceras ratelimit-*, y un 429 incluye retry-after. Consulta Límites de velocidad y Límites y cuotas.

SDK

Las bibliotecas oficiales envuelven la API REST para Node.js, PHP, Laravel, Python, Ruby, Go, Java, .NET y Rust. Todas están en GitHub. Para los comandos de instalación, consulta SDK y bibliotecas, y para ejemplos completos, las guías de frameworks, empezando por Node.js.

Webhooks

Los webhooks envían eventos a tu endpoint en cuanto ocurren: entregas, rebotes, aperturas, clics, correo entrante y cambios en dominios, contactos y otros recursos. Cada petición lleva un array JSON de hasta 100 eventos y va firmada con HMAC-SHA256 en la cabecera X-Emailit-Signature. Las peticiones fallidas se reintentan, con un máximo de 11 intentos. Empieza por Configurar un webhook y Firma de las peticiones.

Servidor MCP y herramientas de IA

El servidor MCP alojado en https://api.emailit.com/mcp ofrece a los asistentes de IA 109 herramientas que cubren toda la API v2, desde el envío de emails hasta las campañas y las automatizaciones. Los asistentes inician sesión con OAuth o con una clave de API, y los plugins de Emailit añaden skills para ChatGPT, Codex, Claude Code, Cursor y Grok.

La documentación también se publica para la IA: cada página tiene una versión en Markdown, y /docs/llms.txt las indexa todas.

Próximos pasos