Referencia de la API
POST /api/v1/send es la API de envío transaccional — un único endpoint versionado y estable. Para contactos, oportunidades y recorridos, mira la API de automatización; para eventos, los webhooks. A diferencia del resto de las rutas de MailInApp (que solo tienen a nuestro propio frontend como llamador y pueden cambiar libremente), esta es un contrato del que depende código de terceros, así que está versionada desde el primer día.
Autenticación
Authorization: Bearer mia_live_...
Una clave faltante o inválida devuelve 401. Las claves se gestionan bajo Desarrolladores en el panel — mira la guía rápida. Una clave revocada deja de funcionar de inmediato.
Solicitud
Content-Type: application/json. Dos formas de solicitud comparten el endpoint — cuál aplica lo decide si projectId está presente.
Formato libre
| Campo | Tipo | Obligatorio | Notas |
|---|---|---|---|
to | string | sí | Una sola dirección de destinatario. |
subject | string | sí | Truncado a 200 caracteres. |
html | string | sí | Enviado tal cual — sin renderizado, sin etiquetas de combinación, sin pipeline del estudio. |
text | string | sí | La parte de texto plano. |
Plantilla
| Campo | Tipo | Obligatorio | Notas |
|---|---|---|---|
to | string | sí | Una sola dirección de destinatario. |
projectId | string | sí | Debe ser un proyecto que poseas — la URL del estudio es /studio/<projectId>. |
mergeData | object | no | Objeto plano { key: value }, hasta 100 campos. Hace las veces de una fila de fuente de datos — se resuelve en las etiquetas de combinación {{field}} del proyecto. Los objetos/arreglos anidados se descartan; null/undefined se convierten en cadenas vacías; todo lo demás se convierte a texto. |
subject | string | no | Por defecto usa el nombre del proyecto si se omite. Las etiquetas de combinación en el asunto se resuelven desde mergeData. Truncado a 200 caracteres. |
Un cuerpo que no coincida con ninguna de las dos formas (por ejemplo, sin to, o sin html/text ni projectId) devuelve 400.
Campos comunes
| Campo | Tipo | Obligatorio | Notas |
|---|---|---|---|
type | "transactional" | "marketing" | no | Por defecto "transactional". Mira abajo. |
from | object | no | Sobrescritura por llamada de la dirección/nombre del remitente — { "email": string, "name"?: string }. Mira abajo. |
senderId | string | no | Sobrescritura por llamada eligiendo una de las identidades de remitente guardadas de tu cuenta en lugar de detallar from en línea. Debe pertenecer a tu cuenta, si no, 400. from tiene prioridad si se dan ambos. |
replyTo | string | no | Dirección Reply-To por llamada. Mira abajo. |
Encabezados
| Encabezado | Obligatorio | Notas |
|---|---|---|
Authorization | sí | Bearer <apiKey>. |
Idempotency-Key | no | Mira idempotencia. |
Respuesta
{ "id": "abc123", "status": "sent" }
status es uno de:
| Estado | Significado |
|---|---|
sent | Entregado con éxito a tu método de envío (relé SMTP o envío nativo). |
suppressed | El destinatario está en tu lista de supresión — mira transaccional vs. marketing — o la dirección no puede recibir correo, en cuyo caso la respuesta también trae "reason": "invalid-address" (mira verificación de correo). No se envió ningún correo; esto no es un error. |
failed | El intento de envío falló (por ejemplo, tu relé SMTP no está configurado, o rechazó el mensaje). Un campo error lleva una razón legible por humanos. |
Códigos de error
| Estado | Significado |
|---|---|
400 | JSON mal formado, una solicitud que no coincide ni con la forma libre ni con la de plantilla, un type inválido, un from inválido o no permitido (mira Dirección de remitente), un replyTo inválido, o (modo plantilla) un projectId que no existe o no es tuyo. También se devuelve cuando la cuenta no tiene un método de envío funcional configurado. |
401 | Encabezado Authorization faltante o inválido, o la clave ha sido revocada. |
404 | (Modo plantilla) el proyecto no existe o no pertenece a tu cuenta — deliberadamente la misma respuesta que "no existe" para evitar filtrar qué IDs de proyecto son válidos para otras cuentas. |
429 | Límite de tasa excedido — mira límites de tasa. Un cuerpo con "code": "sending-ramp" significa que se alcanzó el límite de envío para cuentas nuevas: no se envió nada y la llamada no cuenta para tu cuota de la API de envío. |
422 | Una comprobación de envío rechazó el envío, con un code en el cuerpo (abajo). No se envió nada y la llamada no cuenta para tu cuota de la API de envío. |
Los códigos 422, todos descritos en envío nativo:
code | Significado | Qué hacer |
|---|---|---|
domain-checking | El dominio de envío aún se está comprobando después de verificarse. | Vuelve a intentarlo en unos minutos. |
domain-review | Nuestro equipo está revisando el dominio de envío. | Espera nuestro correo (normalmente en 24 horas), o envía desde otro dominio o a través de tu relé SMTP. |
domain-rejected | El dominio de envío no puede enviar a través de MailInApp. | Contacta con soporte. |
link-review | Se está comprobando un enlace del correo. | Vuelve a intentarlo en unos minutos. |
link-blocked | El correo enlaza a un sitio incluido en listas de sitios no seguros. | Quita el enlace o contacta con soporte. |
content-review | El correo de una cuenta nueva está retenido para una revisión. | Contacta con soporte; reenviar el mismo correo da la misma respuesta hasta que se revise. |
Los códigos domain-* solo se aplican al envío nativo. Una respuesta domain-* solo lleva error y code. Un rechazo por enlace o contenido lleva además el id del envío y "status": "failed". Una respuesta 200 nunca lleva uno de estos códigos.
Se devuelve un 200 con status: "failed" (en lugar de un estado que no sea 2xx) cuando la propia solicitud era válida pero el intento de envío real falló más adelante. Si necesitas distinguir "rechazamos tu solicitud" de "lo intentamos y no salió", revisa status en el cuerpo, no solo el código de estado HTTP.
Transaccional vs. marketing
El campo type controla qué lista de supresión se verifica, reflejando cómo los ESP separan los flujos transaccional y de marketing:
type: "transactional"(por defecto) — omite la supresión por cancelación de suscripción. Un restablecimiento de contraseña o un recibo de pedido no deberían bloquearse solo porque el destinatario canceló la suscripción a tu boletín. Nunca omite la supresión por rebote — una dirección muerta está muerta sin importar la intención.type: "marketing"— se comporta exactamente como un envío de campaña desde el panel: bloqueado tanto por la supresión de cancelación de suscripción como por la de rebote.
Ambos casos devuelven status: "suppressed" en lugar de un error cuando se bloquean.
Dirección de remitente
Por defecto, cada envío usa la identidad de remitente configurada de tu cuenta — la tarjeta "Dirección de remitente" de Configuración → Dominios si estás en envío nativo (SES), o la dirección de remitente configurada de tu relé SMTP en caso contrario. Pasa from para sobrescribirla en una llamada:
{
"to": "[email protected]",
"subject": "Your one-time code",
"html": "<p>Your code is 123456</p>",
"text": "Your code is 123456",
"from": { "email": "[email protected]", "name": "FitConsent Sales Team" }
}
from.email es obligatorio siempre que from esté presente — no hay sobrescritura de solo nombre, así que un valor aquí siempre reemplaza por completo tanto la dirección como el nombre visible para esa llamada. from.name es opcional; omítelo para enviar solo con la dirección simple.
Si tu cuenta envía a través de un dominio verificado (envío nativo/SES), from.email debe ser una dirección de uno de tus propios dominios de envío verificados (por ejemplo, [email protected], no [email protected]) — una cuenta puede verificar más de un dominio, así que cualquiera de ellos está permitido, solo nunca el de alguien más. El envío nativo se ejecuta sobre una única cuenta de AWS de la plataforma compartida entre todos los clientes de MailInApp, así que esta restricción es lo que impide que una cuenta envíe correo que parezca provenir del dominio verificado de otra. En el envío por SMTP no existe tal restricción: el envío sale a través de tu propio relé/credenciales, así que ya es de confianza de la misma forma en que ya lo son las propias reglas de verificación de remitente de tu relé.
senderId (mira la tabla de campos comunes arriba) suele ser la opción más simple cuando ya configuraste una identidad de remitente en el panel. Se resuelve en el propio {email, name, reply-to} de esa identidad sin que tengas que repetirlos en cada llamada.
Un from inválido o no permitido devuelve 400 antes de intentar cualquier envío.
Dirección de Reply-To
Por defecto, las respuestas van a tu Reply-To predeterminado configurado, definido en la página Sending o Domains bajo Configuración según tu método de envío, o a ningún lado si no has configurado uno. Pasa replyTo para sobrescribirlo en una llamada — útil cuando el from visible es una dirección de no-responder pero aun así quieres que una persona vea las respuestas:
{
"to": "[email protected]",
"subject": "Your order shipped",
"html": "<p>Your order is on its way.</p>",
"text": "Your order is on its way.",
"from": { "email": "[email protected]", "name": "FitConsent" },
"replyTo": "[email protected]"
}
A diferencia de from.email, replyTo no tiene restricción de dominio en el envío nativo (SES) — nunca afecta la identidad de envío ni la reputación de entregabilidad, es solo un encabezado que el cliente de correo del destinatario respeta cuando responde. Un replyTo inválido devuelve 400 antes de intentar cualquier envío.
Idempotencia
Pasa un encabezado Idempotency-Key en cualquier llamada que pueda reintentarse — una reentrega de webhook de checkout, un consumidor de cola que vuelve a procesar un mensaje. Una llamada reintentada con la misma clave contra la misma cuenta devuelve el {id, status} de la llamada original sin enviar un segundo correo, incluso si la primera llamada todavía está en curso.
Las claves están vinculadas por cuenta y no tienen vencimiento; reutilizar una clave que ya usaste para un payload diferente es tu propia responsabilidad evitarlo (aun así devolverá el resultado de la primera llamada, no enviará el nuevo payload). Si no pasas una clave, cada llamada envía.
Límites de tasa
Se aplican cuatro topes independientes:
- Por clave de API: un tope de solicitudes por minuto. Excederlo devuelve
429para esa clave específicamente — otras claves de la misma cuenta no se ven afectadas. - Por cuenta, cuota de la API de envío: tu plan incluye un número de llamadas a la API de envío por mes calendario (500/mes en Free). Excederlo devuelve
429hasta que la cuota se reinicia el día 1. - Por cuenta, volumen de envío: el tope acumulado de volumen de envío mensual de tu plan, compartido entre todas las vías de envío (envíos desde el panel, envíos programados, correos de ciclo de vida, y esta API). Este es el mismo tope que protege el resto del envío de tu cuenta — la API de envío no obtiene un presupuesto separado.
- Cuentas nuevas, envío nativo: durante sus primeros 14 días, una cuenta que envía desde su propio dominio a través de MailInApp tiene un límite diario y por hora (100 al día y 50 por hora en Free). Al pasarlo, una llamada devuelve
429con"code": "sending-ramp"y no se cuenta. Vuelve a intentarlo pasada la hora o al día UTC siguiente. Consulta límites de envío para cuentas nuevas.
Detalles del modo de plantilla
Un envío en modo de plantilla renderiza el proyecto vinculado exactamente como un envío normal a un destinatario: los tres niveles del motor de alternativas, los bloques interactivos, y un enlace de vista en vivo personal y firmado construido a partir de mergeData en lugar de una fila de contacto almacenada. Todo lo que sigue se comporta igual que en un envío impulsado por el estudio:
- Los votos de encuesta, calificaciones, envíos de formulario y aperturas se registran y aparecen en la vista de Respuestas del proyecto, atribuidos al contacto cuando el correo está vinculado a uno y, si no, a esta llamada específica de la API.
- El webhook de tu proyecto se dispara por cada evento de interacción, igual que con cualquier otro destinatario.
- Las llamadas recientes (estado, destinatario, marca de tiempo) se listan en la página del panel Desarrolladores como un registro de auditoría.
Contactos vinculados
Cuando to ya es uno de tus contactos, el correo queda vinculado a ese contacto. MailInApp busca la dirección en el listId que pases, si no en la lista de audiencia del propio correo y, si no, en la lista de contactos actualizada más recientemente que la tenga. Un correo vinculado se comporta como uno enviado a ese contacto desde el panel:
- las respuestas, clics y aperturas van a la cronología de actividad y a la puntuación de interacción del contacto, y pueden rellenar campos del contacto e iniciar journeys;
- el bloque de reservas reserva con un clic, sin formulario, y una reserva mueve el trato del contacto como cualquier otra;
- un bloque de Solicitud de reseña con Lo último que pidieron pregunta por el pedido más reciente del contacto en la tienda, y solo un contacto vinculado puede dejar una reseña;
- las cargas útiles del webhook incluyen el contacto.
Las etiquetas de combinación se siguen resolviendo desde mergeData. Si el destinatario no es un contacto, nada cambia: la interacción se atribuye a la llamada de la API, así que las uniones en tu lado deben basarse en el id de la respuesta.