Email API
Envío de emails transaccionales (restablecimiento de contraseña, avisos, confirmaciones) a través de Sendeasy, desde tu propia aplicación, autenticado por el token del propio email — cada email configurado en el proyecto tiene el suyo.
El envío sale por el email dueño del token y consume 1 crédito de email del proyecto. No informas el remitente: es el email del token. ¿Tienes más de un email? Usa el token de aquel por el que quieras enviar.
Requisitos previos
- Token del email — en Canales → Email (o en la tarjeta del email en Canales) → Configuración → sección API de envío. Cada email tiene su propio token; allí también puedes generar uno nuevo (el anterior deja de valer de inmediato).
- El email con estado Verificado (mismo lugar). Sin esto la ruta responde
503 ERR_EMAIL_SENDER_NOT_CONFIGUREDy no sale nada, aunque haya crédito. - Créditos de email disponibles en el plan del proyecto.
Usa GET /api/v1/email/health para comprobar los puntos 1 y 2 sin gastar crédito.
Autenticación
Header obligatorio, con el token del email remitente:
Authorization: Bearer <token_del_email>
El token identifica el email remitente y, a través de él, el proyecto — no hay whatsappId/emailId en la URL.
Compatibilidad: el API Token del proyecto (el mismo de la WABA API) también se acepta en este header. En ese caso el remitente es el primer email verificado del proyecto — útil para integraciones hechas antes del token por email, pero para elegir el remitente usa el token del email.
Endpoints
| Método | Endpoint | Finalidad | Crédito |
|---|---|---|---|
POST | /api/v1/email/send | Enviar email transaccional | 1 por envío |
GET | /api/v1/email/health | Diagnóstico: ¿el email del token está verificado? | no consume |
GET | /api/v1/email/sends/:id | Estado de un envío | no consume |
GET | /api/v1/email/sends | Envíos recientes | no consume |
Límite: 20 envíos por minuto por origen (429 ERR_PUBLIC_EMAIL_RATE_LIMIT). Las consultas de estado tienen su propio límite, de 120 por minuto.
Envío de email
POST /api/v1/email/send
Payload
| Campo | Tipo | Obligatorio | Observaciones |
|---|---|---|---|
to | string o string[] | Sí | hasta 10 destinatarios por envío |
subject | string | Sí | hasta 200 caracteres |
html | string | Uno de los dos | cuerpo HTML, hasta 200.000 caracteres |
text | string | Uno de los dos | cuerpo en texto plano, hasta 20.000 caracteres |
fromName | string | No | nombre visible del remitente (hasta 80 caracteres). La dirección es siempre el email dueño del token |
El remitente (fromEmail) no se acepta en el payload: la ruta usa siempre el email dueño del token. Esto impide que un token envíe en nombre de un email que no es tuyo.
Ejemplo
curl --location 'https://backend.sendeasy.app/api/v1/email/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN_DEL_EMAIL' \
--data '{
"to": "cliente@ejemplo.com",
"subject": "Restablecimiento de contraseña",
"fromName": "Mi Plataforma",
"html": "<p>¡Hola! Haz clic en el enlace de abajo para crear una nueva contraseña.</p>"
}'
Respuesta de éxito:
{
"success": true,
"id": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61"
}
Guarda el id: con él sigues la entrega en GET /api/v1/email/sends/:id. La respuesta confirma que el email fue aceptado para entrega; la entrega final depende del servidor del destinatario.
Diagnóstico de la integración
GET /api/v1/email/health
No consume crédito. Indica si el email del token ya está verificado — la causa más común de que un envío falle aun con crédito disponible.
curl --location 'https://backend.sendeasy.app/api/v1/email/health' \
--header 'Authorization: Bearer TOKEN_DEL_EMAIL'
{
"ok": true,
"senderConfigured": true,
"sender": "no-reply@tuempresa.com",
"domain": "tuempresa.com",
"channelId": 12
}
Con senderConfigured: false, termina de verificar el email en Canales → Email antes de enviar. (Con el API Token del proyecto la respuesta viene sin channelId y dice si el proyecto tiene algún email verificado.)
Estado de los envíos
Cada envío aceptado queda registrado con su estado actual y la línea de tiempo de los eventos de entrega. Consúltalo por el id devuelto en el envío o lista los envíos recientes. Las consultas no consumen crédito.
| Método | Endpoint | Finalidad |
|---|---|---|
GET | /api/v1/email/sends/:id | Estado y línea de tiempo de un envío |
GET | /api/v1/email/sends | Envíos recientes, del más nuevo al más antiguo |
Con el token del email ves los envíos de ese email; con el API Token del proyecto, los de todos los emails del proyecto. Límite de las consultas: 120 solicitudes por minuto por origen, separado del límite de envío.
Estados
status | Significado |
|---|---|
accepted | aceptado por Sendeasy, todavía sin evento de entrega |
sent | salió hacia el servidor del destinatario |
delivery_delayed | el servidor del destinatario aplazó la entrega (se reintenta solo) |
delivered | entregado al servidor del destinatario |
opened | abierto por el destinatario |
clicked | el destinatario hizo clic en un enlace |
bounced | rebotado (buzón inexistente, buzón lleno, bloqueo); el motivo viene en detail |
complained | el destinatario lo marcó como spam |
failed | el envío falló antes de salir |
suppressed | no enviado: la dirección está bloqueada por rebotes o quejas anteriores |
canceled | envío cancelado |
El estado solo avanza: los eventos que llegan fuera de orden (abierto antes de entregado) no lo hacen retroceder, y bounced/complained prevalecen sobre los demás.
opened y clicked dependen de que el seguimiento de aperturas y clics esté activo para el dominio. Sin él, el último estado de un email entregado es delivered.
Consultar un envío
curl --location 'https://backend.sendeasy.app/api/v1/email/sends/9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61' \
--header 'Authorization: Bearer TOKEN_DEL_EMAIL'
{
"id": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61",
"status": "bounced",
"from": "no-reply@tuempresa.com",
"to": ["cliente@ejemplo.com"],
"subject": "Restablecer contraseña",
"createdAt": "2026-11-17T14:02:11.000Z",
"lastEventAt": "2026-11-17T14:02:14.000Z",
"events": [
{ "status": "sent", "at": "2026-11-17T14:02:12.000Z", "detail": null },
{
"status": "bounced",
"at": "2026-11-17T14:02:14.000Z",
"detail": { "type": "Permanent", "subType": "General", "message": "The recipient's mailbox does not exist." }
}
]
}
Los envíos hechos antes de que existiera este registro también se pueden consultar por el id: en ese caso la respuesta trae el estado actual, sin la línea de tiempo.
Listar envíos
curl --location 'https://backend.sendeasy.app/api/v1/email/sends?status=bounced&since=2026-11-01' \
--header 'Authorization: Bearer TOKEN_DEL_EMAIL'
| Parámetro | Observaciones |
|---|---|
status | uno de los estados de la tabla anterior |
to | solo envíos a este destinatario |
since / until | rango por fecha del envío (ISO 8601) |
page | página, desde 1 |
limit | elementos por página, hasta 100 (por defecto 50) |
{ "sends": [ { "id": "9fbbb3a9-...", "status": "bounced", "...": "..." } ], "count": 1, "page": 1, "hasMore": false }
En la consola
Los mismos envíos aparecen en Canales → Email → Configuración → API de envío → Envíos por la API, con filtro por estado y la línea de tiempo de cada envío.
Webhook de estado
Si el proyecto tiene un webhook configurado (en Integraciones), cada evento de un envío por la API llega en el evento message_status, con channel: "email":
{
"event": "message_status",
"channel": "email",
"channelId": "uuid-del-canal-de-email",
"data": {
"messageId": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61",
"status": "delivered",
"currentStatus": "delivered",
"timestamp": "2026-11-17T14:02:13.000Z",
"to": ["cliente@ejemplo.com"],
"subject": "Restablecer contraseña",
"detail": null
}
}
status es el evento que acaba de llegar; currentStatus, el estado del envío después de él.
Créditos y reembolso
- Cada envío aceptado descuenta 1 crédito de email del proyecto.
- Sin crédito, la ruta responde
402 ERR_NO_EMAIL_CREDITSantes de cualquier débito. - Si el envío falla después del débito (remitente no configurado, proveedor no disponible), el crédito se reembolsa automáticamente y la ruta responde
502/503.
Códigos de error
| HTTP | error | Cuándo ocurre |
|---|---|---|
| 400 | ERR_EMAIL_INVALID_BODY | payload inválido (sin to/subject, sin html ni text, ningún destinatario válido) |
| 400 | ERR_EMAIL_TOO_MANY_RECIPIENTS | más de 10 destinatarios en un envío |
| 401 | ERR_API_TOKEN_NOT_PROVIDED / ERR_API_TOKEN_INVALID | header ausente o token inválido/inactivo |
| 402 | ERR_NO_EMAIL_CREDITS | proyecto sin créditos de email |
| 400 | ERR_VALIDATION | filtro inválido al listar envíos (el campo viene en params.field) |
| 404 | ERR_EMAIL_SEND_NOT_FOUND | id de envío desconocido o de otro email/proyecto |
| 429 | ERR_PUBLIC_EMAIL_RATE_LIMIT | más de 20 envíos o 120 consultas por minuto |
| 502 | ERR_EMAIL_SEND_FAILED | fallo del proveedor al enviar (crédito reembolsado) |
| 502 | ERR_EMAIL_STATUS_UNAVAILABLE | no se pudo consultar ahora el estado de un envío antiguo; inténtalo de nuevo |
| 503 | ERR_EMAIL_SENDER_NOT_CONFIGURED | el email del token aún no está verificado (con token del email, antes de cualquier débito) |
Email API vs. integración Custom
Sendeasy ofrece dos formas de enviar email por API — elige según el tipo de token que tengas:
Email API (/api/v1/email/send) | Custom (/api/integration/generic) | |
|---|---|---|
| Token | token del email (Canales → Email → API de envío) | token de integración ligado a un canal de email |
| Remitente | el email dueño del token | el canal del token |
| Uso típico | emails transaccionales desde tu propia aplicación | integraciones por canal, con bcc, inReplyTo, etc. |
Detalles de la integración Custom en /es/server/integracoes.
Seguridad: trata el token como una contraseña. Nunca lo incrustes en JavaScript del navegador, repositorios públicos o logs — guárdalo en variables de entorno o en un secret manager en tu servidor.