Emails
Envía un email o un lote, prográmalo y sigue su recorrido desde que se acepta hasta que se entrega.
Un email es una solicitud POST /emails, o un mensaje a través del relay SMTP. BillionSend lo comprueba, lo guarda y devuelve un id de inmediato. El envío ocurre en segundo plano, así que un 200 significa que el email está aceptado, no entregado.
Enviar un email
import { BillionSend } from "@billionsend/node";
const bs = new BillionSend(); // reads BILLIONSEND_API_KEY
const { data, error } = await bs.emails.send({
from: "Acme <hello@mail.example.com>",
to: ["success@simulator.amazonses.com"],
subject: "Welcome",
html: "<p>Thanks for signing up.</p>",
});
La misma llamada con curl:
curl -X POST https://api.billionsend.com/emails \
-H "Authorization: Bearer $BILLIONSEND_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Acme <hello@mail.example.com>",
"to": ["success@simulator.amazonses.com"],
"subject": "Welcome",
"html": "<p>Thanks for signing up.</p>"
}'
from: debe estar en un dominio verificado de tu equipo.to,cc,bcc,reply_to: una dirección o una lista.to,ccybccjuntos admiten como máximo 50 destinatarios.htmlytext: se necesita al menos uno. No se admite enviar con el id de una plantilla. Una plantilla es contenido que copias en un envío masivo.tags,headers,attachments: consulta Conceptos básicos de la API para ver las reglas, los límites de los adjuntos y la idempotencia.topic_id: se omite a los destinatarios que se excluyeron de ese tema.
La dirección success@simulator.amazonses.com de estos ejemplos es la del simulador: no envía correo a nadie, así que úsala para probar.
Enviar un lote
POST /emails/batch acepta un array de hasta 100 emails. Por defecto, un email no válido hace fallar todo el lote. Añade la cabecera x-batch-validation: permissive para aceptar los válidos: data lista sus ids y errors lista los demás por posición.
Programar, cambiar, cancelar
Añade scheduled_at para enviar más tarde, hasta con 30 días de antelación. Acepta una hora ISO 8601 con desfase, o una hora relativa como in 2 hours. Mientras un email está programado, PATCH /emails/{id} cambia su hora y POST /emails/{id}/cancel lo cancela.
Seguir un email
GET /emails/{id} devuelve el email con last_event, su resultado más reciente, y un score de Insights de entregabilidad. En el panel, Emails lista todos los emails y muestra sus eventos en orden. Los cuerpos y el historial se conservan 30 días.
| Evento | Significado |
|---|---|
email.scheduled |
Aceptado, a la espera de su hora. |
email.sent |
Entregado para su envío. |
email.delivered |
El servidor del destinatario lo aceptó. |
email.delivery_delayed |
La entrega se retrasa y se reintentará. |
email.bounced |
El servidor del destinatario lo rechazó. |
email.complained |
El destinatario lo marcó como spam. |
email.failed |
No se pudo enviar. El evento indica el motivo. |
email.suppressed |
No se envió porque todos los destinatarios están suprimidos o dados de baja. |
email.opened, email.clicked |
El destinatario lo abrió o hizo clic en un enlace, si el rastreo está activado. |
Cada evento también se te puede enviar como webhook.
Qué detiene o retiene un envío
Un envío se rechaza con un error 4xx que indica el motivo cuando:
- el dominio del remitente no está verificado (
422); - todos los destinatarios están suprimidos (
422 all_recipients_suppressed); - has superado el volumen de tu plan (
429); - tu tasa de rebote o de quejas ha pausado el envío (
403 sending_paused).
Parte del correo se acepta pero se retiene, y sale más tarde: un dominio nuevo que supera su tope diario, o correo que espera a que se restablezca un límite. Consulta Límites de envío. La API y el relay SMTP aplican las mismas reglas.