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
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
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]"
}'to: un único destinatario por email. Para varios, usa el envío por lotes.from:correo@dominiooNombre <correo@dominio>. El dominio tiene que pertenecer a tu organización; con claveslive, 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) ytext(hasta 256 KB): hace falta al menos uno. Si solo envíashtml, Vemudo genera la versión de texto.replyTo: dirección a la que responderá el destinatario.headers: hasta 10 cabeceras personalizadas, con prefijoX-(no se admitenX-SES-*niX-Vemudo-*). Además se admitenList-Unsubscribe(<https://…>,<mailto:…>o ambos, separados por coma) yList-Unsubscribe-Post(exactamenteList-Unsubscribe=One-Click, que exige un destinohttpsenList-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) ocritical. Loscritical(restablecer contraseña, códigos de acceso) usan una cola de mayor prioridad.
Envío con plantilla
html y text puedes indicar una plantilla publicada y sus variables. Ver Plantillas.
{
"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.
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" }
]
}'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
{
"to": "[email protected]",
"subject": "Tu factura",
"text": "Adjuntamos tu factura.",
"attachments": [
{ "filename": "factura.pdf", "content": "JVBERi0x...", "contentType": "application/pdf" }
]
}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
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.
{
"to": "[email protected]",
"subject": "Recordatorio",
"text": "Mañana a las 10:00",
"scheduledAt": "2026-11-12T09:30:00+01:00"
}Cancelar un email
curl -X POST https://api.vemudo.com/v1/emails/$ID/cancel \
-H "Authorization: Bearer $VEMUDO_API_KEY"409 not_cancellable.
Idempotencia
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 testy otralivetambién da422 idempotency_key_reused.
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:
accepted, queued, rendered | |
submitted | |
delivered | |
bounced | errorCode empieza por bounce_. |
complained | |
suppressed | |
cancelled | |
failed |
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
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]):
bounce@ o rebote@ | |
softbounce@ | |
complaint@ o queja@ | |
delay@ |
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
400 | validation_failed | errors[] indica cuál. |
402 | plan_quota_exceeded | live). Ver Planes y cuotas. |
422 | from_domain_not_found | |
422 | from_domain_not_verified | live). |
429 | daily_limit_exceeded | |
503 | suppression_unavailable |