Saltar al contenido

Enviar emails

Envía emails transaccionales con la API de Vemudo: envío simple, lotes de hasta 100, adjuntos, programados, idempotencia, cancelación y pruebas con claves test.

Por Equipo Vemudo · Actualizado el

El envío es asíncrono: la API valida tu petición, guarda el email y responde 202 con su identificador. El envío real, los reintentos y la entrega ocurren después, y los ves con GET /v1/emails/{id} o con webhooks. Necesitas una clave con scope send o full.

Envío simple

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 Alba <[email protected]>",
    "to": "[email protected]",
    "subject": "Tu pedido",
    "html": "<p>Gracias por tu compra.</p>",
    "text": "Gracias por tu compra.",
    "replyTo": "[email protected]"
  }'

Reglas de los campos:

  • to: un único destinatario por email. Para varios, usa el envío por lotes.
  • from: correo@dominio o Nombre <correo@dominio>. El dominio tiene que pertenecer a tu organización; con claves live, además verificado. Si lo omites se usa el remitente por defecto de la organización.
  • subject: de 1 a 255 caracteres. Es obligatorio, salvo que uses una plantilla.
  • html (hasta 512 KB) y text (hasta 256 KB): hace falta al menos uno. Si solo envías html, Vemudo genera la versión de texto.
  • replyTo: dirección a la que responderá el destinatario.
  • headers: hasta 10 cabeceras personalizadas, con prefijo X- (no se admiten X-SES-* ni X-Vemudo-*). Además se admiten List-Unsubscribe (<https://…>, <mailto:…> o ambos, separados por coma) y List-Unsubscribe-Post (exactamente List-Unsubscribe=One-Click, que exige un destino https en List-Unsubscribe). Con ellas, los clientes de correo compatibles muestran su propio botón de baja; atender esa baja corre de tu cuenta.
  • tags: hasta 10 pares clave y valor para clasificar tus envíos. Aparecen en el email consultado y en los webhooks.
  • category: transactional (por defecto) o critical. Los critical (restablecer contraseña, códigos de acceso) usan una cola de mayor prioridad.

El asunto y el nombre del remitente rechazan los caracteres de control de dirección bidireccional.

Envío con plantilla

En lugar de html y text puedes indicar una plantilla publicada y sus variables. Ver Plantillas.

json
{
  "to": "[email protected]",
  "templateId": "bienvenida",
  "variables": { "nombre": "Lucía" }
}

Envío por lotes

POST /v1/emails/batch admite de 1 a 100 emails en una sola petición. La validación es de todo o nada: si uno falla, no se acepta ninguno y el error indica el índice (emails[3].to). Los lotes no admiten attachments ni scheduledAt.

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]", "subject": "Hola Ana", "text": "Hola" },
      { "to": "[email protected]", "subject": "Hola Luis", "text": "Hola" }
    ]
  }'

La respuesta es 202 con { "data": [{ "id": "..." }] } en el mismo orden. Los destinatarios que están en la lista de bajas también reciben un id, con estado suppressed.

Adjuntos

Hasta 10 adjuntos y 10 MB en total ya decodificados, con el contenido en base64:

json
{
  "to": "[email protected]",
  "subject": "Tu factura",
  "text": "Adjuntamos tu factura.",
  "attachments": [
    { "filename": "factura.pdf", "content": "JVBERi0x...", "contentType": "application/pdf" }
  ]
}

Se rechazan con 422 attachment_type_blocked los tipos peligrosos (ejecutables, scripts, instaladores) y se mira cada extensión del nombre, así que factura.exe.pdf también cae. Si el total excede el límite, la respuesta es 413 attachments_too_large. El tamaño máximo de la petición es de 15 MB en /v1/emails y de 5 MB en el lote.

Envíos programados

Con scheduledAt (ISO 8601 con zona horaria) el email sale en ese momento. Puede estar hasta 72 horas en el futuro; más allá, 422 scheduled_at_too_far. Una fecha en el pasado o a menos de 5 segundos se envía enseguida.

json
{
  "to": "[email protected]",
  "subject": "Recordatorio",
  "text": "Mañana a las 10:00",
  "scheduledAt": "2026-11-12T09:30:00+01:00"
}

Cancelar un email

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

Solo se puede cancelar un email programado cuya hora aún no ha llegado y que no ha empezado a enviarse. En otro caso la respuesta es 409 not_cancellable.

Idempotencia

Añade una cabecera Idempotency-Key (de 1 a 255 caracteres ASCII imprimibles) a cada envío importante, por ejemplo con el número de pedido. Si tu cliente reintenta tras un corte de red, no se duplica el email:

  • Misma clave y mismo cuerpo en 24 horas: devuelve la respuesta original, con la cabecera Idempotent-Replayed: true.
  • Misma clave con un cuerpo distinto: 422 idempotency_key_reused.
  • Misma clave mientras la primera petición sigue en curso: 409 idempotency_in_progress; reintenta en unos segundos.
  • La clave se evalúa por entorno: usarla con una clave test y otra live también da 422 idempotency_key_reused.

La idempotencia también funciona en el envío por lotes.

Estados de un email

GET /v1/emails/{id} devuelve el email con su línea de eventos. El campo status toma uno de estos valores:

EstadoSignificado
accepted, queued, renderedAdmitido y en cola.
submittedEntregado al proveedor de correo.
deliveredEntregado en el buzón del destinatario.
bouncedRebotó; errorCode empieza por bounce_.
complainedEl destinatario lo marcó como spam.
suppressedNo se envió porque la dirección está en la lista de bajas y bloqueos. No consume cuota.
cancelledCancelado antes de enviarse.
failedNo se pudo enviar.

Con clave send solo ves los emails creados con esa misma clave; con read o full, los de toda la organización. Siempre del mismo entorno que la clave.

Probar con claves test

Con una clave test el email no sale, pero tu integración ve todo el ciclo. El dominio reservado simulator.vemudo.test genera resultados concretos según la parte local de la dirección (admite etiqueta +, por ejemplo [email protected]):

DirecciónResultado simulado
cualquier otraEntrega
bounce@ o rebote@Rebote permanente
softbounce@Rebote temporal (buzón lleno)
complaint@ o queja@Entrega y queja de spam
delay@Retraso y entrega después

Las claves test tienen un tope de 100 envíos diarios. Un rebote permanente simulado añade la dirección a tu lista de bajas, tal y como ocurriría en producción: el siguiente envío a esa misma dirección saldrá como suppressed.

Errores habituales

RespuestaCódigoCausa
400validation_failedAlgún campo no es válido; errors[] indica cuál.
402plan_quota_exceededHas agotado la cuota del plan (solo claves live). Ver Planes y cuotas.
422from_domain_not_foundEl dominio del remitente no es de tu organización.
422from_domain_not_verifiedEl dominio no está verificado o está pausado (claves live).
429daily_limit_exceededHas llegado al límite diario de envío de tu organización.
503suppression_unavailableNo se pudo comprobar la lista de bajas; el envío se rechaza por seguridad. Reintenta.

La lista completa está en Errores y límites.