Enviar correo transaccional
Envía un correo transaccional mediante la API pública. Crea o actualiza automáticamente el contacto destinatario.
Contenido obligatorio: un ID de template, o bien tanto subject como body. Los campos de la plantilla pueden sobrescribirse con campos explícitos en la solicitud.
Remitente: from es obligatorio salvo que uses una plantilla que ya tenga configurado un from. El dominio del remitente debe estar verificado.
Varios destinatarios: cuando to es un array, cada destinatario se procesa secuencialmente con su propio upsert de contacto y su propio correo renderizado — no existe semántica de envío por lotes. El envío siempre es inmediato; para envíos programados, usa una Campaña.
Adjuntos: hasta 10 adjuntos por correo y 10 MB en total de forma predeterminada. El tamaño total del mensaje no puede superar los 40 MB.
Authorization
ApiKeyAuth Autenticación mediante clave de API. Las claves secretas (sk_*) son obligatorias en todos los endpoints excepto /v1/track. Las claves públicas (pk_*) solo funcionan con el endpoint /v1/track para el seguimiento de eventos desde el cliente. El proyecto se deriva automáticamente de la clave.
In: header
Header Parameters
Clave opcional que garantiza que esta solicitud se ejecute como máximo una vez. Si la clave ya fue usada por tu proyecto, la solicitud se rechaza con 409 en lugar de ejecutarse una segunda vez. Las claves están limitadas a tu proyecto, expiran a las 24 horas y deben tener entre 1 y 255 caracteres ASCII imprimibles.
length <= 255Request Body
application/json
Correo(s) del destinatario. Puede ser un string, un objeto con {name, email}, o un array de cualquiera de los dos.
Asunto del correo. Obligatorio si no se proporciona template. No puede contener saltos de línea.
1 <= length <= 998Cuerpo del correo (HTML). Obligatorio si no se proporciona template.
1 <= lengthID de la plantilla a usar para este correo. Cuando se proporciona, usa el subject, body, from y reply-to configurados en la plantilla. Puedes sobrescribirlos proporcionando explícitamente los campos subject, body, from o reply en la solicitud. Las variables de la plantilla se completan a partir del campo data.
Dirección de correo del remitente (requiere un dominio verificado). Obligatorio salvo que uses una plantilla que ya tenga configurada una dirección 'from'. Puede ser un string (p. ej., 'hello@example.com') o un objeto con {name, email} (p. ej., {name: 'My App', email: 'hello@example.com'}).
Obsoleto. Nombre para mostrar del remitente. Se prefiere from: { name, email }. Solo se usa como alternativa cuando from es un string y no se ha definido un nombre ahí.
Estado de suscripción a aplicar al destinatario. Para contactos nuevos, el valor por defecto en /v1/send es false. Para contactos existentes, omitir este campo conserva su estado actual — pasa true o false para cambiarlo explícitamente. Un cambio emite contact.subscribed o contact.unsubscribed.
Variables para el renderizado de la plantilla y actualizaciones de datos del contacto. Cada valor puede ser:
- Un valor primitivo (string, número, booleano) — se guarda en el contacto y queda disponible como variable de plantilla.
null— elimina el campo del contacto.- Un string vacío — se ignora (no sobrescribe datos existentes).
- Un objeto
{ value, persistent: false }— se usa solo para este envío, sin guardarse en el contacto (ideal para códigos de restablecimiento de contraseña o enlaces mágicos de un solo uso).
Las claves reservadas (id, bitelio_id, bitelio_email, email, unsubscribeUrl, subscribeUrl, manageUrl) se filtran silenciosamente.
Encabezados de correo personalizados. Los nombres de encabezado no pueden contener \r\n. Los valores de encabezado están limitados a 998 caracteres y no pueden contener \r\n (se rechaza la inyección de encabezados).
Dirección de respuesta (reply-to).
emailAdjuntos del correo. Límite predeterminado: 10 adjuntos y 10 MB en total. El tamaño completo del mensaje no puede superar los 40 MB.
items <= 10Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.bitelio.com/v1/send" \ -H "Content-Type: application/json" \ -d '{ "to": "user@example.com", "subject": "Password Reset Request", "body": "<h1>Reset Your Password</h1><p>Click the link to reset: {{resetLink}}</p>", "data": { "resetLink": "https://example.com/reset/abc123" } }'{
"success": true,
"data": {
"emails": [
{
"contact": {
"id": "cnt_abc123",
"email": "user@example.com"
},
"email": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf"
}
],
"timestamp": "2025-01-15T10:30:00.000Z"
}
}{
"code": 0,
"error": "string",
"message": "string",
"time": 0
}{
"code": 0,
"error": "string",
"message": "string",
"time": 0
}{
"success": false,
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "Idempotency-Key \"order-1234-receipt\" has already been used",
"statusCode": 409,
"requestId": "8f14e45f-ceea-467a-9575-1f0f38e0b1c2",
"details": {
"key": "order-1234-receipt",
"originalRequest": "POST /v1/send",
"originalRequestAt": "2025-01-15T10:30:00.000Z",
"originalStatusCode": 200
},
"suggestion": "This Idempotency-Key was already used, so the request was refused rather than performed twice. Generate a new key for a genuinely new request."
},
"timestamp": "2025-01-15T10:31:00.000Z"
}