Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

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, cc y bcc juntos admiten como máximo 50 destinatarios.
  • html y text: 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.

¿Te ha resultado útil esta página?