---
title: Emails
description: Envía un email o un lote, prográmalo y sigue su recorrido desde que se acepta hasta que se entrega.
seo:
  title: API para enviar emails
ai:
  exclude: true
---

Un email es una solicitud `POST /emails`, o un mensaje a través del [relay SMTP](/docs/es/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

```ts
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`:

```bash
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](/docs/es/concepts/domains) 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](/docs/es/concepts/templates) es contenido que copias en un envío masivo.
- `tags`, `headers`, `attachments`: consulta [Conceptos básicos de la API](/docs/es/api-reference/basics) 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](/docs/es/concepts/topics).

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](/docs/es/concepts/deliverability-insights). 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](/docs/es/concepts/tracking) está activado. |

Cada evento también se te puede enviar como [webhook](/docs/es/concepts/webhooks).

## 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](/docs/es/concepts/suppressions) (`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](/docs/es/concepts/sending-limits). La API y el relay SMTP aplican las mismas reglas.
