Saltar al contenido

Emails

Enviar, cancelar y consultar emails y sus eventos.

Listar emails

GET/v1/emails

Scope necesario: read o full. Una clave full incluye send y read.

Emails del entorno de la clave (una clave test nunca ve emails live y al revés), del más reciente al más antiguo. Requiere scope read (o full). Cada elemento es el mismo objeto que GET /v1/emails/{id} sin la línea de eventos (/v1/emails/{id}/events). Filtros combinables; paginación por cursor (nextCursor) con los mismos filtros.

Parámetros

CampoDescripción
cursorstring · query Cursor opaco: usa el nextCursor de la página anterior con los mismos filtros.
limitnumber · query Elementos por página (1-100, 25 por defecto).
statusstring · query Estados separados por comas: accepted, queued, rendered, submitted, delivered, rejected, suppressed, bounced, complained, cancelled, failed.
tostring · query Destinatario: si contiene @, dirección exacta; si no, prefijo (mínimo 3 caracteres).
fromstring · query Dirección del remitente (exacta, sin el nombre).
subjectstring · query El asunto contiene este texto (mínimo 3 caracteres).
tagstring · query Etiqueta nombre:valor, o nombre para cualquier valor.
campaignIdstring · query
templateIdstring · query Id de la plantilla.
apiKeyIdstring · query Solo los creados con esa clave API.
originstring · query valores: api | test_send | campaign
sincestring · query Creados desde esta fecha (ISO 8601, inclusive).
untilstring · query Creados hasta esta fecha (ISO 8601, inclusive; una fecha sin hora cubre el día completo).

Respuestas

  • 200
    CampoDescripción
    data[]object[] · obligatorio
    data[].idstring · obligatorio
    data[].objectstring · obligatoriovalores: email
    data[].statusstring · obligatoriovalores: accepted | queued | rendered | submitted | delivered | rejected | suppressed | bounced | complained | cancelled | failed
    data[].environmentstring · obligatoriovalores: test | live
    data[].categorystring · obligatoriovalores: critical | transactional
    data[].fromstring · obligatorioej.: Tienda <[email protected]>
    data[].tostring · obligatorioej.: [email protected]
    data[].subjectstring · obligatorio
    data[].tagsobject · obligatorio
    data[].scheduledAtstring | null · obligatorio
    data[].createdAtstring · obligatorio
    data[].submittedAtstring | null · obligatorio
    data[].errorCodestring | null · obligatorio
    data[].templateobject | null · obligatorio
    data[].template.idstring · obligatorio
    data[].template.aliasstring · obligatorio
    data[].template.versionnumber · obligatorio
    nextCursorstring | null · obligatorioCursor de la página siguiente (null en la última).

Ejemplo

bash
curl "https://api.vemudo.com/v1/emails?status=bounced,failed&since=2026-10-01&limit=50" -H "Authorization: Bearer $VEMUDO_API_KEY"

Enviar un email

POST/v1/emails

Scope necesario: send o full. Una clave full incluye send y read.

Admite el email y responde 202 { id }; el envío es asíncrono. Un destinatario por email (varios: /v1/emails/batch).

Con una plantilla publicada (sin html/text; subject es opcional y sustituye al de la plantilla):

bash
curl -X POST https://api.vemudo.com/v1/emails \
  -H "Authorization: Bearer $VEMUDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"[email protected]","templateId":"bienvenida","variables":{"nombre":"Lucía"}}'

Errores de plantilla: 422 template_not_found, template_not_published, template_render_failed (con errors[] de parte y línea, sin valores) y template_render_too_large.

Parámetros

CampoDescripción
Idempotency-Keystring · cabecera 1-255 caracteres ASCII imprimibles. Misma clave y mismo cuerpo en 24 h devuelven la misma respuesta (Idempotent-Replayed: true).

Cuerpo application/json

CampoDescripción
fromstring email o Nombre <email>. Si falta, se usa el remitente por defecto de la organización.ej.: Tienda Alba <[email protected]>
tostring · obligatorioUn único destinatario. Varios: POST /v1/emails/batch.ej.: [email protected]
subjectstring Obligatorio salvo con templateId; con plantilla, si viene, sustituye al asunto de la plantilla (sin variables).longitud 1–255
templateIdstring Alias o id de una plantilla publicada de la organización. Excluyente con html y text.ej.: bienvenida
templateVersionnumber Versión publicada concreta; sin valor, la publicada más alta. Exige templateId.mínimo 1 · ej.: 2
variablesobject Datos para las variables de la plantilla (objeto JSON de hasta 32 KB y 10 niveles). Exige templateId.ej.: {"nombre":"Lucía"}
htmlstring Máximo 512 KB.
textstring Máximo 256 KB. Hace falta html o text.
replyTostring ej.: [email protected]
headersobject Hasta 10 cabeceras X-* (no X-SES-* ni X-Vemudo-*), valores de hasta 998 caracteres. También List-Unsubscribe (<https://…> y/o <mailto:…>) y List-Unsubscribe-Post (exactamente List-Unsubscribe=One-Click, exige un destino https en List-Unsubscribe).
tagsobject Hasta 10 pares; reglas de tags de SES.
categorystring valores: critical | transactional · por defecto: transactional
scheduledAtstring ISO 8601 con zona; hasta 72 h en el futuro.ej.: 2026-11-01T10:00:00+01:00
attachments[]object[] Hasta 10 adjuntos, 10 MB decodificados en total.
attachments[].filenamestring longitud 0–255 · ej.: factura.pdf
attachments[].contentstring Contenido en base64.
attachments[].contentTypestring ej.: application/pdf

Respuestas

  • 202
    Email admitido: { id }.
  • 402
    Cuota del plan agotada (code: plan_quota_exceeded). Problem Details con extensions { metric: "emails_sent", used, reserved, cap, periodEnd, policy }. En un lote, si no cabe entero se rechaza completo. Se renueva en el siguiente periodo o al cambiar de plan / autorizar excedente en el panel (Uso y facturación). Solo cuentan los envíos con clave live.

Ejemplo

bash
curl -X POST https://api.vemudo.com/v1/emails \
  -H "Authorization: Bearer $VEMUDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1042" \
  -d '{"from":"Tienda <[email protected]>","to":"[email protected]","subject":"Tu pedido","html":"<p>Gracias</p>"}'

Enviar hasta 100 emails

POST/v1/emails/batch

Scope necesario: send o full. Una clave full incluye send y read.

Validación todo o nada. Sin attachments ni scheduledAt. Respuesta 202 { data: [{ id }] } en el mismo orden (los suprimidos también traen id).

Parámetros

CampoDescripción
Idempotency-Keystring · cabecera 1-255 caracteres ASCII imprimibles. Misma clave y mismo cuerpo en 24 h devuelven la misma respuesta (Idempotent-Replayed: true).

Cuerpo application/json

CampoDescripción
emails[]object[] · obligatorio1–100 elementos
emails[].fromstring email o Nombre <email>. Si falta, se usa el remitente por defecto de la organización.ej.: Tienda Alba <[email protected]>
emails[].tostring · obligatorioUn único destinatario. Varios: POST /v1/emails/batch.ej.: [email protected]
emails[].subjectstring Obligatorio salvo con templateId; con plantilla, si viene, sustituye al asunto de la plantilla (sin variables).longitud 1–255
emails[].templateIdstring Alias o id de una plantilla publicada de la organización. Excluyente con html y text.ej.: bienvenida
emails[].templateVersionnumber Versión publicada concreta; sin valor, la publicada más alta. Exige templateId.mínimo 1 · ej.: 2
emails[].variablesobject Datos para las variables de la plantilla (objeto JSON de hasta 32 KB y 10 niveles). Exige templateId.ej.: {"nombre":"Lucía"}
emails[].htmlstring Máximo 512 KB.
emails[].textstring Máximo 256 KB. Hace falta html o text.
emails[].replyTostring ej.: [email protected]
emails[].headersobject Hasta 10 cabeceras X-* (no X-SES-* ni X-Vemudo-*), valores de hasta 998 caracteres. También List-Unsubscribe (<https://…> y/o <mailto:…>) y List-Unsubscribe-Post (exactamente List-Unsubscribe=One-Click, exige un destino https en List-Unsubscribe).
emails[].tagsobject Hasta 10 pares; reglas de tags de SES.
emails[].categorystring valores: critical | transactional · por defecto: transactional

Respuestas

  • 202
    Emails admitidos.
  • 402
    Cuota del plan agotada (code: plan_quota_exceeded). Problem Details con extensions { metric: "emails_sent", used, reserved, cap, periodEnd, policy }. En un lote, si no cabe entero se rechaza completo. Se renueva en el siguiente periodo o al cambiar de plan / autorizar excedente en el panel (Uso y facturación). Solo cuentan los envíos con clave live.

Ejemplo

bash
curl -X POST https://api.vemudo.com/v1/emails/batch \
  -H "Authorization: Bearer $VEMUDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":[{"to":"[email protected]"}]}'

Eventos de un email

GET/v1/emails/{id}/events

Scope necesario: read o full. Una clave full incluye send y read.

Línea temporal del email con datos saneados por evento (rebote, queja, retraso, fallo o enlace de un clic). Mismo alcance que GET /v1/emails/{id}: otra organización, otro entorno o un id mal formado dan 404 not_found.

Parámetros

CampoDescripción
idstring · ruta · obligatorio

Respuestas

  • 200
    CampoDescripción
    data[]object[] · obligatorio
    data[].typestring · obligatorioaccepted, queued, rendered, submitted, delivered, rejected, suppressed, bounced, complained, cancelled, failed, deferred, opened, clicked, unsubscribed.ej.: bounced
    data[].occurredAtstring · obligatorio
    data[].dataobject · obligatorioDatos saneados: bounced (bounceType, subType, smtpStatus), complained (feedbackType), deferred (delayType), failed (errorCode), clicked (url). Nunca el diagnóstico del proveedor.
    nextCursorstring | null · obligatorio

Ejemplo

bash
curl https://api.vemudo.com/v1/emails/$EMAIL_ID/events -H "Authorization: Bearer $VEMUDO_API_KEY"

Consultar un email

GET/v1/emails/{id}

Scope necesario: send o read o full. Una clave full incluye send y read.

Con clave send solo los creados con esa misma clave; con read o full, toda la organización (siempre del entorno de la clave). status: accepted, queued, rendered, submitted, delivered, bounced (rebotó; errorCode bounce_*), complained (el destinatario lo marcó como spam), suppressed, cancelled o failed. La línea de eventos incluye deferred, bounced y complained.

Parámetros

CampoDescripción
idstring · ruta · obligatorio

Respuestas

  • 200
    Email con su línea de eventos.

Ejemplo

bash
curl https://api.vemudo.com/v1/emails/$ID \
  -H "Authorization: Bearer $VEMUDO_API_KEY"

Cancelar un email programado

POST/v1/emails/{id}/cancel

Scope necesario: send o full. Una clave full incluye send y read.

Solo si scheduledAt está en el futuro y el email no ha empezado a enviarse; si no, 409 not_cancellable.

Parámetros

CampoDescripción
idstring · ruta · obligatorio

Respuestas

  • 200
    Email cancelado.

Ejemplo

bash
curl -X POST https://api.vemudo.com/v1/emails/$ID/cancel \
  -H "Authorization: Bearer $VEMUDO_API_KEY"