> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Resumen de mensajería

> Envío transaccional de email y SMS por API: requisitos, facturación, remitentes y plantillas. Consulta el esquema del request, códigos de respuesta.

## Qué hacen estos endpoints

Permiten enviar **email** y **SMS** transaccionales desde tu backend o integraciones, **fuera** de los [Workflows](/es/workflows/overview). Cada envío exitoso se factura como el resto del marketplace: **cupos de pack de ejecuciones** (si aplica) o **saldo de tokens** de la organización.

No sustituyen acciones de flujo como “Enviar notificación”; son APIs HTTP dedicadas bajo la ruta de marketplace.

## URL base y rutas

```
POST https://api.gu1.ai/marketplace/messaging/send-email
POST https://api.gu1.ai/marketplace/messaging/send-sms
```

Usa el host de API de tu entorno si es distinto (p. ej. staging).

## Autenticación y organización

Misma autenticación que el resto de la API gu1. Ver [Autenticación](/es/api-reference/authentication).

```bash theme={null}
Authorization: Bearer TU_API_KEY
Content-Type: application/json
```

* **API key:** queda asociada a una organización; normalmente no hace falta cabecera extra.
* **Sesión de usuario (p. ej. desde el panel):** si el usuario tiene varias organizaciones, indica la organización objetivo:

```http theme={null}
X-Organization-ID: <uuid-de-organización>
```

## Integraciones del marketplace (obligatorio)

Antes de llamar, la organización debe tener activa la integración correspondiente en **Applications** (Marketplace):

| Canal | Código de integración (referencia) |
| ----- | ---------------------------------- |
| Email | `global_sender_email`              |
| SMS   | `global_sender_sms`                |

Si está desactivada, la API responde **`400`** indicando que hay que activar Email o SMS.

El **proveedor de mensajería** de la plataforma (`MS_PROVIDER_URL` en el servidor) también debe estar configurado.

## Facturación y saldo

Si el precio es **distinto de cero** (`base_price_cents`), la API **antes** de enviar comprueba que haya:

1. **Al menos una ejecución** disponible en el **pack** de esa integración, o
2. **Saldo suficiente** en tokens.

Si no, **`400`** con mensaje de saldo insuficiente.\
Los mensajes de error de esta API están en **inglés** en el campo `error`.

## Email: dominios verificados y remitentes

Para enviar desde tu dominio (ej. `noreply@tudominio.com`):

1. Añade y **verifica** el dominio en **Configuración → Email → Dominios** (DNS).
2. Opcional: crea un **remitente** en **Configuración → Email → Remitentes** si querés fijar nombre visible o reutilizar un UUID.

En la API podés usar **solo uno** de:

* **`fromEmail`** — dirección completa; el dominio debe estar **verificado** en tu org. Si el dominio no está registrado o no pasó verificación DNS, la API responde **`400`** con `success: false` y un `error` en inglés (detalle en [Enviar email](/es/api-reference/messaging/send-email#remitente-personalizado-fromemail)).
* **`fromSenderId`** — UUID de un remitente ya guardado en tu org.

Si no envías ninguno, se usa el remitente **por defecto de la plataforma Gu1** (comportamiento esperado, no un error).

## Contenido del mensaje

1. **Plantilla guardada:** `templateId` + `templateParams` opcional. No mezclar con cuerpo inline.
2. **Cuerpo inline:** `htmlBody` / `textBody` (email) o `body` (SMS); podés usar **`templateParams`** para `{{variables}}` también en el asunto (email).
3. **Email sin plantilla:** `subject` obligatorio; al menos `htmlBody` o `textBody`.

Los IDs de plantilla se pueden copiar desde **Configuración de organización → Applications → Templates de mensajes**.

## Respuesta

```json theme={null}
{ "success": true, "messageId": "..." }
```

```json theme={null}
{ "success": false, "error": "..." }
```

## Rutas de prueba

Las rutas **`/marketplace/messaging/.../test`** son para pruebas rápidas; para producción usá **`send-email`** y **`send-sms`**.

## Siguientes pasos

<CardGroup cols={2}>
  <Card title="Enviar email" icon="envelope" href="/es/api-reference/messaging/send-email">
    `POST .../send-email`
  </Card>

  <Card title="Enviar SMS" icon="message" href="/es/api-reference/messaging/send-sms">
    `POST .../send-sms`
  </Card>
</CardGroup>