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

  1. 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).
  2. El email con estado Verificado (mismo lugar). Sin esto la ruta responde 503 ERR_EMAIL_SENDER_NOT_CONFIGURED y no sale nada, aunque haya crédito.
  3. 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.

Endpoints

MétodoEndpointFinalidadCrédito
POST/api/v1/email/sendEnviar email transaccional1 por envío
GET/api/v1/email/healthDiagnóstico: ¿el email del token está verificado?no consume
GET/api/v1/email/sends/:idEstado de un envíono consume
GET/api/v1/email/sendsEnvíos recientesno 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

CampoTipoObligatorioObservaciones
tostring o string[]Síhasta 10 destinatarios por envío
subjectstringSíhasta 200 caracteres
htmlstringUno de los doscuerpo HTML, hasta 200.000 caracteres
textstringUno de los doscuerpo en texto plano, hasta 20.000 caracteres
fromNamestringNonombre visible del remitente (hasta 80 caracteres). La dirección es siempre el email dueño del token

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étodoEndpointFinalidad
GET/api/v1/email/sends/:idEstado y línea de tiempo de un envío
GET/api/v1/email/sendsEnví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

statusSignificado
acceptedaceptado por Sendeasy, todavía sin evento de entrega
sentsalió hacia el servidor del destinatario
delivery_delayedel servidor del destinatario aplazó la entrega (se reintenta solo)
deliveredentregado al servidor del destinatario
openedabierto por el destinatario
clickedel destinatario hizo clic en un enlace
bouncedrebotado (buzón inexistente, buzón lleno, bloqueo); el motivo viene en detail
complainedel destinatario lo marcó como spam
failedel envío falló antes de salir
suppressedno enviado: la dirección está bloqueada por rebotes o quejas anteriores
canceledenví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.

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ámetroObservaciones
statusuno de los estados de la tabla anterior
tosolo envíos a este destinatario
since / untilrango por fecha del envío (ISO 8601)
pagepágina, desde 1
limitelementos 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_CREDITS antes 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

HTTPerrorCuándo ocurre
400ERR_EMAIL_INVALID_BODYpayload inválido (sin to/subject, sin html ni text, ningún destinatario válido)
400ERR_EMAIL_TOO_MANY_RECIPIENTSmás de 10 destinatarios en un envío
401ERR_API_TOKEN_NOT_PROVIDED / ERR_API_TOKEN_INVALIDheader ausente o token inválido/inactivo
402ERR_NO_EMAIL_CREDITSproyecto sin créditos de email
400ERR_VALIDATIONfiltro inválido al listar envíos (el campo viene en params.field)
404ERR_EMAIL_SEND_NOT_FOUNDid de envío desconocido o de otro email/proyecto
429ERR_PUBLIC_EMAIL_RATE_LIMITmás de 20 envíos o 120 consultas por minuto
502ERR_EMAIL_SEND_FAILEDfallo del proveedor al enviar (crédito reembolsado)
502ERR_EMAIL_STATUS_UNAVAILABLEno se pudo consultar ahora el estado de un envío antiguo; inténtalo de nuevo
503ERR_EMAIL_SENDER_NOT_CONFIGUREDel 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)
Tokentoken del email (Canales → Email → API de envío)token de integración ligado a un canal de email
Remitenteel email dueño del tokenel canal del token
Uso típicoemails transaccionales desde tu propia aplicaciónintegraciones por canal, con bcc, inReplyTo, etc.

Detalles de la integración Custom en /es/server/integracoes.

Essa informação foi útil?