> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/sending-invites.md).

# Envío de invitaciones (API de correo)

Active correos electrónicos personalizados de invitación a encuestas desde sus propios sistemas.

La API de invitaciones convierte BAI Analytics en el brazo de envío de tu propio flujo de trabajo: tu sistema decide *a quién* a quién enviar correos y *cuándo* (un ticket de soporte cerrado, un pedido entregado, una incorporación completada), y BAI Analytics renderiza la plantilla de invitación, la envía, rastrea la entrega y vincula las respuestas con tus contactos.

La división de responsabilidades es deliberada: **el diseño vive en el panel, la activación vive en la API.** La plantilla de correo, la marca y la encuesta se crean en la plataforma, donde pueden previsualizarse y revisarse; la API solo proporciona destinatarios y variables. Eso impide que una clave comprometida reescriba lo que reciben tus clientes.

***

### Requisitos previos

Tres cosas deben ser ciertas para que funcione el primer envío. Las tres pueden inspeccionarse mediante `GET /sources/{id}/invite-template`, así que intégralo en tus comprobaciones de configuración:

1. **Una `send`- clave de API con alcance.** El envío de correos a personas tiene un alcance separado del envío de datos; `all` lo incluye. Consulta [Autenticación y claves de API](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/authentication.md).
2. **El propio dominio de envío verificado de tu organización.** Los envíos desde la API nunca usan el remitente compartido de BAI Analytics: el volumen automatizado depende de tu reputación de envío, no de la nuestra. Hasta que el dominio se verifique, recibirás un `SENDER_DOMAIN_NOT_VERIFIED` error. Configúralo en **Detalles de la organización → Envío de correo electrónico** ([Configuración](/boundaryai-docs/boundaryai-docs-es/cuenta-y-administracion/updating-settings.md#email-sending)).
3. **Una plantilla de invitación en la fuente**, diseñada en la plataforma. La comprobación de la plantilla devuelve sus **claves de variables** (por ejemplo, `first_name`, `order_id`) para que tu integración pueda validar sus datos antes de enviar.

***

### El flujo de envío

#### 1. Comprobar preparación

```bash
curl https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/sources/9021/invite-template \\
  -H "Authorization: Bearer $BAI_API_KEY"
```

Devuelve si una plantilla está `configurada`, su `variables`, `sender_domain_verified`, `sending_enabled`, y el uso de la cuota del día.

#### 2. Previsualizar con `dry_run`

```bash
curl -X POST https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/sources/9021/invites \\
  -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \\
  -d '{
    "dry_run": true,
    "recipients": [
      {"email": "jamie@example.com",
       "external_id": "cus_310",
       "variables": {"first_name": "Jamie", "order_id": "A-1042"}}
    ]
  }'
```

Una ejecución de prueba renderiza los correos y reporta lo que *sería* ocurriría (`would_accept`, `skipped_already_invited`, `invalid`) sin enviar nada. Úsalo en CI y antes del primer envío en producción.

#### 3. Enviar

Quita `dry_run` y la misma llamada devuelve **202** con una `distribution_id`. Los envíos son transaccionales: de 1 a 1,000 destinatarios por llamada, cada uno con su propia `variables`. Los destinatarios se añaden a la lista de encuestados de la fuente, y cada uno recibe un **enlace de encuesta personalizado**, que es lo que vincula su respuesta eventual con tu `external_id`.

#### 4. Seguir el resultado

* `GET /invites/{distribution_id}`: estado general y recuentos (`total`, `enviados`, `fallidos`, `omitido`).
* `GET /invites/{distribution_id}/recipients`: resultados por destinatario, incluido el **estado de entrega** informado por el proveedor de correo (entregado, rebotado, diferido) y tu `external_id`, con paginación por cursor.
* O evita la consulta periódica: el **`invites.completed`** webhook se activa cuando la distribución finaliza, y **`invite.bounced`** se activa por cada rebote o denuncia de spam. Consulta [Webhooks](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/webhooks.md).

***

### Controles de seguridad (y por qué no son opcionales)

Existen para que un error de automatización no dañe tu reputación de envío, la cual tarda meses en reconstruirse:

* **Nunca envíes dos invitaciones por defecto.** Una dirección que ya recibió esta encuesta se omite; pasa `resend: true` solo cuando realmente lo pretendas.
* **La supresión siempre se aplica.** Las direcciones dadas de baja, rebotadas o que presentaron quejas nunca vuelven a recibir correos, incluso si tu sistema sigue enviándoles correos.
* **Cuota móvil de 24 horas** por organización (2.000 invitaciones por defecto; ampliable bajo solicitud). La comprobación de la plantilla muestra el uso de hoy, y los envíos que superan la cuota fallan limpiamente con `INVITE_QUOTA_EXCEEDED` en lugar de quedar en cola.
* **Pausa automática por tasa de quejas.** Si las quejas de spam se disparan en una ventana de 30 días, el envío se pausa antes de que los proveedores de buzones penalicen tu dominio.
* **1.000 destinatarios por llamada.** Agrupa las listas más grandes en varias llamadas; cada una devuelve su propia `distribution_id`.

***

### Vincular las respuestas de nuevo con tus datos

La `external_id` lo que configuras por destinatario atraviesa todo el ciclo: aparece en las filas de resultados por destinatario, en la `invite.bounced` carga útil, y, como el enlace de la encuesta es personalizado, en la propia respuesta. Usa el mismo identificador que usas en [envíos de retroalimentación](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/pushing-feedback.md) (`customer_id`) y puedes conectar *invitado → respondió → lo que dijo* completamente en tu propio almacén de datos.