---
title: Envíos masivos
description: Redacta, programa y haz un envío masivo de correos a muchos contactos, con campos de combinación, ritmo de envío y enlace de baja por dominio.
seo:
  title: Envío masivo de correos
ai:
  exclude: true
---

Un envío masivo de correos es un solo email enviado a muchos contactos: a todos, a un [segmento](/docs/es/concepts/segments) o a un [tema](/docs/es/concepts/topics). Redáctalo en el panel, en **Envíos masivos**, con campos de combinación por contacto, o créalo con la API.

## Cómo hacer un envío masivo de correos

```ts
import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.broadcasts.create({
  name: "November news",
  segment_id: "SEGMENT_ID",
  from: "Acme <news@mail.example.com>",
  subject: "What's new",
  html: "<p>Hi {{{FIRST_NAME|there}}},</p><p>...</p><p><a href=\"{{{UNSUBSCRIBE_URL}}}\">Unsubscribe</a></p>",
});

if (error) throw error;

await bs.broadcasts.send(data.id, { scheduled_at: "in 1 hour" });
```

Si omites `scheduled_at`, el envío masivo sale de inmediato. En `from` necesitas un dominio de envío verificado. En el editor puedes partir de una [plantilla](/docs/es/concepts/templates) guardada.

## Ciclo de vida

```
draft → scheduled → sending → sent
              ↘ canceled
              ↘ failed
```

- Un envío masivo nuevo es un **borrador**, y solo un borrador se puede editar.
- `POST /broadcasts/{id}/send` lo envía ahora o en `scheduled_at`.
- `POST /broadcasts/{id}/cancel` cancela un envío masivo programado, o uno que ya está saliendo. Los emails ya enviados no se retiran. `canceled_remaining` en la respuesta indica cuántos se detuvieron, y `sent_count` en una consulta indica cuántos salieron.
- Se pueden eliminar los borradores y los envíos masivos fallidos que no enviaron nada.
- En la API, `scheduled` y `sending` se leen ambos como `queued`. Un envío masivo se lee como `queued` con `sent_at` vacío hasta que sale su último email.

## Quién lo recibe

Cada destinatario se comprueba cuando sale el envío masivo. Quedan fuera:

- los contactos que figuran como `unsubscribed` en todo el equipo y los contactos que se dieron de baja del dominio de envío del envío masivo;
- los contactos que se excluyeron del tema del envío masivo;
- las direcciones de la [lista de supresión](/docs/es/concepts/suppressions).

El número de destinatarios que muestra el panel antes de enviar ya excluye a estos contactos.

## El dominio de envío

El dominio de envío del envío masivo es el de su dirección `from`, que se devuelve como `domain_id`. Decide:

- **Qué bajas se aplican.** Se omite a las personas que se dieron de baja de este dominio. Consulta [Bajas](/docs/es/concepts/unsubscribes).
- **Cómo lo ve el destinatario.** El enlace de baja abre la [página de baja](/docs/es/concepts/unsubscribes) propia de ese dominio, en su propio subdominio si lo tiene.
- **Qué audiencia se permite.** Un tema o segmento ligado a otro dominio se rechaza con `422`, de modo que una marca nunca escribe a la audiencia de otra.

Un dominio no se puede eliminar mientras lo use un envío masivo programado o en curso (`409`).

## Campos de combinación y enlaces de baja

- Los valores por contacto, como `{{{FIRST_NAME|there}}}`, se rellenan para cada destinatario. Consulta [Plantillas](/docs/es/concepts/templates).
- Cada email de un envío masivo lleva las cabeceras `List-Unsubscribe` de un clic y un enlace de baja alojado. Para colocar el enlace en el cuerpo, escribe `{{{UNSUBSCRIBE_URL}}}`.

## Ritmo de envío

Un envío masivo que cabe en la capacidad disponible sale enseguida. Uno más grande sale en oleadas durante los días siguientes. El email transaccional nunca queda retenido detrás de un envío masivo: se envía antes que los destinatarios restantes de un envío masivo.

La llamada de envío te dice qué esperar:

```json
{
  "id": "8c1f0b8e-…",
  "finishes_at": "2026-09-18T13:26:05Z",
  "estimated": true,
  "warning": { "code": "paced", "days": 3, "message": "…" }
}
```

- `finishes_at` es la hora estimada en que sale el último email. Es una estimación, y otros envíos pueden moverla.
- `warning` aparece cuando el envío necesita más de una oleada: `paced` cuando la audiencia es mayor que la capacidad disponible ahora, `queued_behind` cuando otros envíos van primero.
- Mientras sale, `GET /broadcasts/{id}` incluye un `finishes_at` y un `sent_count` en vivo.
- Una audiencia que necesitaría más de 24 días de capacidad se rechaza con `422 broadcast_too_large`. Divídela en segmentos más pequeños.

## Duplicar un envío masivo

`POST /broadcasts/{id}/duplicate` copia cualquier envío masivo, incluso uno enviado o fallido, en un borrador nuevo. En el panel, usa **Duplicar** en el menú del envío masivo.

- **Se copian:** el segmento, el tema, el remitente, el asunto, `reply_to`, el texto de vista previa y el contenido.
- **No se copian:** la programación, los recuentos y el progreso de entrega. La copia es un borrador normal.
- El nombre es el del original seguido de ` (copy)`.

## Cuando un envío masivo falla

Un envío masivo termina en `failed` cuando se aceptó pero no puede salir, o cuando el envío siguió fallando. Entonces `GET /broadcasts/{id}` devuelve `failure_reason` y `failed_at`. Los emails ya entregados siguen enviados, y los propietarios del equipo reciben un email una sola vez.

| `failure_reason` | Significado |
| --- | --- |
| `domain_missing` | Se eliminó el dominio de envío. |
| `sender_domain_mismatch` | `from` ya no está en el dominio con el que se programó el envío masivo. |
| `topic_other_domain` | El tema está ligado a otro dominio. |
| `segment_other_domain` | El segmento está ligado a otro dominio. |
| `domain_unverified` | El dominio de envío siguió sin verificar durante unas horas de reintentos. |
| `retries_exhausted` | Otro error siguió fallando hasta agotar los reintentos. |

Para llegar a la audiencia, duplica el envío masivo, corrige la causa en el borrador nuevo y envíalo.

## Cuando se rechaza un envío masivo

- `403 sending_paused`: tu tasa de rebote o de quejas es demasiado alta. Consulta [Límites de envío](/docs/es/concepts/sending-limits).
- `403 broadcasts_paused`: los envíos masivos están en pausa, ya sea en toda la plataforma mientras se recuperan las tasas o para tu equipo por decisión de BillionSend. El email transaccional no se ve afectado.
- `403 inbox_send_policy`: el remitente está en tu dominio de bandejas de entrada compartido, que no puede hacer envíos masivos.

Cuando un envío masivo alcanza el volumen de tu plan, el resto de su audiencia espera y sale cuando hay hueco. Consulta [Planes y límites](/docs/es/billing).

Consulta la [referencia de la API](/docs/es/api-reference) para ver todos los endpoints de envíos masivos.
