# ruiv.ai — catálogo completo de flujos

> ruiv.ai — plataforma de correo transaccional y marketing operable por humanos (UI), por agentes (MCP, OAuth) y por código (REST, API key). Esta es la documentación legible por IA: úsala para entender cada flujo y guiar/ejecutar por el usuario.

Regla de oro para agentes: Antes de enviar correos reales (send_email, send_broadcast, A/B con send=true) o de ejecutar acciones de infra/destructivas, CONFIRMA con el usuario. La autenticación del agente es OAuth: NO se necesita API key.

Leyenda disponibilidad: ok = disponible · pending = existe en UI, aún no por esa superficie · none = no aplica.

## Conexión & identidad

### Conectar el agente (MCP / OAuth)
- id: connect-agent
- objetivo: Quiero operar ruiv.ai desde mi agente o chat.
- actor: user
- UI: /docs — Sección MCP → Copiar https://ruiv.ai/api/mcp → En Claude: Settings → Connectors → Add custom connector → Autorizar por OAuth
- MCP: whoami — El handshake entrega instructions; primer tool recomendado whoami.
- REST: no aplica
- resultado: El agente queda autenticado con la identidad del usuario y ve sus workspaces.
- errores:
  - Token vencido: "401 invalid_token" → Reconectar el connector por OAuth.
- pistas IA: Si el usuario dice 'conéctame', dale la URL y los 3 clics. | Recalca que NO necesita API key.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Conectar por API key (REST)
- id: connect-api-key
- objetivo: Quiero integrar el envío desde mi código.
- actor: developer
- UI: /api-keys — Crear API key (rv_live_…) → Elegir scope: full | sending | read
- MCP: (sin tools) — Sin tool de gestión de keys (filosofía OAuth-only).
- REST: HEADER Authorization: Bearer rv_live_… (scope full|sending|read)
- resultado: API key creada (se muestra una sola vez).
- pistas IA: Recomienda el scope mínimo: 'sending' para solo enviar, 'read' para solo consultar.
- disponibilidad: ui=ok, mcp=pending, rest=ok

### Saber quién soy / mis workspaces
- id: whoami
- objetivo: ¿Qué cuenta y workspaces tengo?
- actor: agent
- UI: /overview — Badge de usuario → Selector de workspace
- MCP: whoami — Devuelve email + workspaces (id, nombre, rol).
- REST: no aplica
- resultado: Identidad + lista de workspaces.
- pistas IA: SIEMPRE corre whoami al inicio para orientarte. | Usa el primer workspace si no se especifica.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Crear workspace
- id: create-workspace
- objetivo: Quiero un nuevo espacio para esta marca o cliente.
- actor: user
- UI: /overview — Selector → Crear workspace
- MCP: create_workspace — Registra owner + siembra plan Free.
- REST: no aplica
- resultado: Workspace nuevo (id, nombre, slug); el usuario queda owner.
- pistas IA: Sugiérelo si whoami no devuelve workspaces.
- disponibilidad: ui=ok, mcp=ok, rest=none

## Remitente & dominios

### Enviar desde el remitente del sistema
- id: send-from-system
- objetivo: Quiero mandar ya, sin configurar DNS.
- actor: user
- UI: /emails — Dejar el remitente por defecto al enviar
- MCP: send_email — Sin 'from' usa el remitente del sistema.
- REST: POST /api/emails (scope sending)
- resultado: Envío permitido desde el remitente del sistema (sujeto a límites de plan/sandbox).
- pistas IA: Úsalo para 'probar rápido'; para marca propia ofrece add-domain o subdominio delegado.
- disponibilidad: ui=ok, mcp=ok, rest=ok

### Agregar y verificar un dominio propio
- id: add-verify-domain
- objetivo: Quiero enviar desde @mimarca.com.
- actor: user
- UI: /domains — Agregar dominio → Publicar los DNS (DKIM/SPF/DMARC) → Verificar
- MCP: add_domain, verify_domain — add_domain devuelve DNS; repetir verify_domain hasta 'verified'.
- REST: no aplica
- resultado: Dominio 'verified'; su remitente se acepta (anti-spoofing).
- errores:
  - DNS no propagó: "estado pending/failed" → Esperar propagación y reintentar verify_domain.
- pistas IA: Si el usuario no maneja DNS, ofrece el subdominio delegado o delega la tarea por correo.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Subdominio de envío delegado (sin DNS del cliente)
- id: delegated-subdomain
- objetivo: No quiero tocar mi DNS; háganlo ustedes.
- actor: agent
- UI: no aplica
- MCP: provision_sending_subdomain — Crea {slug}.envia.ruiv.ai en Mailgun + DNS en la zona de ruiv.ai.
- REST: no aplica
- resultado: Remitente delegado listo (hola@{slug}.envia.ruiv.ai), verificado tras propagar.
- pistas IA: Ideal para no-técnicos. | Confirma el slug antes de provisionar (acción de infra).
- disponibilidad: ui=pending, mcp=ok, rest=none

## Plantillas & marca

### Crear plantilla (la IA escribe el HTML)
- id: create-template
- objetivo: Diséñame un correo de bienvenida bonito y guárdalo.
- actor: agent
- UI: /templates/new — Editor de plantilla
- MCP: create_template — La IA genera el HTML (inline CSS, tablas) y lo pasa en 'html'.
- REST: no aplica
- resultado: Plantilla guardada (template_id) reutilizable en envíos/broadcasts/journeys.
- pistas IA: Usa merge tags ({{first_name}}) y previsualiza antes. | Ofrece la galería si quieren arrancar de un diseño base.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Galería + Brand Kit (arranque rápido)
- id: template-gallery
- objetivo: Dame una plantilla ya hecha con mi marca.
- actor: agent
- UI: /templates/gallery — Elegir plantilla de la galería
- MCP: list_template_gallery, create_template_from_gallery — Clona aplicando logo/colores/fuente del Brand Kit y conserva merge tags.
- REST: no aplica
- resultado: Plantilla editable horneada con la marca.
- pistas IA: Configura el Brand Kit antes para que la marca se aplique.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Ver / editar / borrar plantilla
- id: manage-template
- objetivo: Quiero gestionar mis plantillas.
- actor: agent
- UI: /templates — Acciones por fila
- MCP: list_templates, get_template, update_template, delete_template
- REST: no aplica
- resultado: Plantilla listada / vista / actualizada / eliminada.
- pistas IA: Confirma antes de delete_template (irreversible).
- disponibilidad: ui=ok, mcp=ok, rest=none

### Configurar Brand Kit
- id: brand-kit
- objetivo: Usen mi logo y mis colores.
- actor: user
- UI: /templates/brand-kit — Logo, colores, fuente, nombre
- MCP: get_brand_kit, set_brand_kit — Colores en hex.
- REST: no aplica
- resultado: Brand Kit guardado; se aplica a las plantillas de la galería.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Previsualizar con merge tags (sin enviar)
- id: preview-template
- objetivo: ¿Cómo le llega al destinatario?
- actor: agent
- UI: /templates — Vista previa en el editor
- MCP: preview_template — Render con datos de muestra; escapa HTML.
- REST: no aplica
- resultado: Subject + HTML renderizados con un contacto de muestra.
- pistas IA: Pasa 'sample' (email) para datos realistas.
- disponibilidad: ui=ok, mcp=ok, rest=none

## Envío transaccional

### Enviar un correo (1:1)
- id: send-email
- objetivo: Manda este correo a ana@cliente.com.
- actor: agent
- precondiciones: Remitente del sistema o dominio verificado
- UI: /emails — (seguimiento de enviados; el envío 1:1 es por API/MCP)
- MCP: send_email — Con template_id toma subject+html; los args lo sobrescriben.
- REST: POST /api/emails (scope sending)
- resultado: email_id + estado (queued→sent→delivered).
- errores:
  - from no verificado: "from_not_verified / dominio no habilitado" → Verificar dominio, usar subdominio delegado o el remitente del sistema.
  - Sobre cuota del plan: "429 send_limit_exceeded" → Mejorar plan o esperar al periodo.
  - Falla del proveedor: "502 delivery_error" → Reintentar; ver /status.
- pistas IA: CONFIRMA antes de enviar a destinatarios reales. | Con 1 destinatario que es contacto, se personaliza con sus datos.
- disponibilidad: ui=ok, mcp=ok, rest=ok

### Personalización por contacto (merge tags)
- id: merge-tags
- objetivo: Que diga el nombre de cada quien.
- actor: agent
- UI: no aplica
- MCP: send_email, preview_template — {{first_name}}, {{last_name}}, {{name}}, {{email}}, {{props.X}}, fallback {{x|"hola"}}. En HTML se escapa.
- REST: POST /api/emails (scope sending)
- resultado: Cada destinatario recibe el contenido con sus datos.
- pistas IA: Valida con preview_template antes de mandar.
- disponibilidad: ui=ok, mcp=ok, rest=ok

### Ver estado / seguimiento de un correo
- id: track-email
- objetivo: ¿Llegó el correo?
- actor: agent
- UI: /emails — Estado por fila (Tabla/Grid)
- MCP: list_emails, get_email — get_email incluye eventos de entrega.
- REST: GET /api/emails/{id} (scope read)
- resultado: Estado: queued · sent · delivered · bounced · complained · failed.
- disponibilidad: ui=ok, mcp=ok, rest=ok

### Idempotencia (REST)
- id: idempotent-send
- objetivo: No quiero duplicar envíos al reintentar.
- actor: developer
- UI: no aplica
- MCP: (sin tools) — El agente debe evitar reintentos ciegos.
- REST: POST /api/emails (header Idempotency-Key) (scope sending)
- resultado: Reintentos seguros sin duplicar.
- disponibilidad: ui=none, mcp=none, rest=ok

## Audiencias & contactos

### Crear audiencia
- id: create-audience
- objetivo: Quiero una lista de contactos.
- actor: agent
- UI: /audiences — Nueva audiencia
- MCP: create_audience
- REST: no aplica
- resultado: Audiencia creada.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Agregar contacto
- id: add-contact
- objetivo: Añade a juan@x.com a la lista.
- actor: agent
- UI: /audiences — Agregar contacto
- MCP: add_contact — Puede disparar journeys.
- REST: no aplica
- resultado: Contacto agregado a la audiencia.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Importar en lote (CSV/Excel)
- id: import-contacts
- objetivo: Sube esta lista de 2,000 contactos.
- actor: agent
- UI: /audiences — Importar
- MCP: import_contacts — CSV email,nombre,apellido. Si mandan Excel, la IA lo convierte a CSV antes.
- REST: no aplica
- resultado: Resumen: insertados/duplicados/inválidos/omitidos.
- pistas IA: Confirma la audiencia destino y reporta el resumen.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Etiquetas (tags)
- id: tags
- objetivo: Etiqueta a estos contactos como 'vip'.
- actor: agent
- UI: /audiences — Tags por contacto
- MCP: add_tag, remove_tag, list_tags — Sirven para targeting de broadcasts.
- REST: no aplica
- resultado: Contacto etiquetado/desetiquetado.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Segmentos por reglas
- id: segments
- objetivo: Los que abrieron la campaña X y son plan pro.
- actor: agent
- UI: /audiences — Crear segmento por reglas
- MCP: preview_segment, create_segment_rule, create_segment — preview_segment cuenta sin guardar; create_segment_rule materializa.
- REST: no aplica
- resultado: segment_id + count; usable en broadcasts/journeys.
- pistas IA: SIEMPRE preview_segment antes de crear, para mostrar el conteo.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Temas de suscripción
- id: topics
- objetivo: Quiero categorías a las que la gente se suscribe.
- actor: agent
- UI: /audiences — Temas
- MCP: create_topic
- REST: no aplica
- resultado: Tema creado (public/private, opt-in por defecto).
- disponibilidad: ui=ok, mcp=ok, rest=none

### Leer contactos / segmentos / temas
- id: read-contacts
- objetivo: Muéstrame mis contactos y segmentos.
- actor: agent
- UI: /audiences — Listas y detalle
- MCP: (sin tools) — Aún no por MCP (list_contacts/get_contact/list_segments/list_topics) — llega como resources en v3.
- REST: no aplica
- resultado: Listado de contactos/segmentos/temas.
- disponibilidad: ui=ok, mcp=pending, rest=none

## Campañas (broadcasts)

### Crear y enviar un broadcast (normal)
- id: broadcast
- objetivo: Manda este newsletter a la audiencia.
- actor: agent
- UI: /broadcasts — Nuevo broadcast → Elegir audiencia/plantilla → Enviar
- MCP: send_broadcast — send_broadcast envía uno YA CREADO. create_broadcast (normal) aún no por MCP → llega en v3.
- REST: no aplica
- resultado: Broadcast enviado (total/sent/failed).
- pistas IA: Si piden 'crea y manda' por chat, crea en UI o usa A/B (sí permite crear por MCP).
- disponibilidad: ui=ok, mcp=pending, rest=none

### Targeting (incluir/excluir)
- id: broadcast-targeting
- objetivo: Manda solo a los 'vip' menos los que se dieron de baja.
- actor: agent
- UI: /broadcasts — Configurar segmentos/tags
- MCP: send_broadcast — include/exclude por segmentos y tags. Las bajas nunca reciben.
- REST: no aplica
- resultado: Universo = audiencia + incluidos − excluidos − bajas.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Prueba A/B
- id: ab-test
- objetivo: Prueba 2 asuntos y manda el ganador.
- actor: agent
- UI: /broadcasts — A/B
- MCP: create_ab_broadcast, ab_report — 2–5 variantes; con send=true manda la muestra; el ganador sale solo al cerrar la ventana.
- REST: no aplica
- resultado: Muestra enviada; ganadora al resto al vencer la ventana.
- pistas IA: Confirma antes de send=true.
- disponibilidad: ui=ok, mcp=ok, rest=none

## Automatizaciones (journeys)

### Crear automatización + pasos + activar
- id: journey
- objetivo: Cuando etiquete a alguien 'vip', mándale un correo tras 1 día.
- actor: agent
- UI: /automations — Constructor visual
- MCP: create_journey, add_journey_step, activate_journey — Pasos: wait/send/condition/tag/exit. Requiere ≥1 paso para activar.
- REST: no aplica
- resultado: Journey activo que inscribe y avanza solo.
- pistas IA: Confirma antes de activar (empieza a inscribir y enviar).
- disponibilidad: ui=ok, mcp=ok, rest=none

### Disparadores de inscripción
- id: journey-triggers
- objetivo: ¿Cómo decido a quién inscribir?
- actor: agent
- UI: /automations — Configurar disparador
- MCP: create_journey, update_journey — tag_added (con tag), contact_added (con audience_id), signup.
- REST: no aplica
- resultado: Disparador configurado.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Pausar / listar / reportar
- id: journey-manage
- objetivo: Pausa esta automatización y dime cómo va.
- actor: agent
- UI: /automations — Estado y reporte
- MCP: pause_journey, list_journeys, journey_report
- REST: no aplica
- resultado: Journey pausado / listado / reporte de inscritos por estado.
- disponibilidad: ui=ok, mcp=ok, rest=none

## Onboarding agéntico

### Diagnóstico de readiness
- id: setup-readiness
- objetivo: ¿Qué me falta para salir en vivo?
- actor: agent
- UI: /settings — (diagnóstico vía agente)
- MCP: setup_readiness, setup_status — Dice qué falta (dominio, correo de auth, app) y qué rol técnico atender.
- REST: no aplica
- resultado: Lista de bloqueos + a quién delegar cada uno.
- disponibilidad: ui=ok, mcp=ok, rest=none

### Delegar tarea técnica por correo
- id: delegate-task
- objetivo: No manejo DNS; que lo haga mi técnico.
- actor: agent
- UI: no aplica
- MCP: delegate_setup_task — Envía un tutorial autocontenido al responsable (DNS/dev/CTO).
- REST: no aplica
- resultado: Correo enviado al responsable; seguimiento con setup_status.
- pistas IA: Confirma antes (envía un correo real).
- disponibilidad: ui=pending, mcp=ok, rest=none

### Conectar/Configurar el Auth del cliente (Supabase)
- id: client-auth
- objetivo: Que los correos de auth de mi app salgan por ruiv.ai.
- actor: agent
- UI: no aplica
- MCP: connect_supabase_auth, configure_oauth_provider, set_auth_settings — Vía Management API del Supabase del cliente. El PAT NO se almacena.
- REST: no aplica
- resultado: Send Email Hook / providers / settings configurados en el Supabase del cliente.
- pistas IA: Confirma (toca infra del cliente). | Pide el PAT solo para configurar; no se guarda.
- disponibilidad: ui=none, mcp=ok, rest=none

## Operación & observabilidad

### Logs de API
- id: logs
- objetivo: Quiero ver el log de una request.
- actor: agent
- UI: /logs — Tabla de logs
- MCP: get_log — get_log por id; list_logs aún no por MCP → llega en v3 (resource).
- REST: no aplica
- resultado: Registro: método, ruta, status, latencia, request/response.
- disponibilidad: ui=ok, mcp=pending, rest=none

### Webhooks (eventos de entrega)
- id: webhooks
- objetivo: Quiero recibir eventos (delivered/bounce) en mi endpoint.
- actor: user
- UI: /webhooks — Agregar webhook
- MCP: (sin tools) — Sin tools de webhooks por MCP.
- REST: no aplica
- resultado: Webhook configurado; ruiv.ai despacha eventos firmados.
- disponibilidad: ui=ok, mcp=pending, rest=none

### Inbound (recibir correo)
- id: inbound
- objetivo: Quiero recibir correos entrantes.
- actor: user
- UI: /inbound — Configurar MX + webhook
- MCP: (sin tools) — Sin tools de inbound por MCP.
- REST: no aplica
- resultado: Correos entrantes aparecen al verificar MX/webhook.
- disponibilidad: ui=ok, mcp=pending, rest=none

### Métricas
- id: metrics
- objetivo: Dame el panel de envíos/aperturas/clics.
- actor: user
- UI: /metrics — Dashboard
- MCP: ab_report, journey_report — Métricas globales del workspace aún no por MCP → llega en v3 (resource).
- REST: no aplica
- resultado: Panel de métricas (UI) / reportes A-B y journey (MCP).
- disponibilidad: ui=ok, mcp=pending, rest=none

### Plan, límites y facturación
- id: billing
- objetivo: ¿Cuál es mi plan y mi consumo?
- actor: user
- UI: /settings — Tab Facturación → Ir a Facturación
- MCP: (sin tools) — El envío está gateado por la cuota del plan (send_limit_exceeded).
- REST: no aplica
- resultado: Plan, consumo y suscripción (Stripe).
- disponibilidad: ui=ok, mcp=pending, rest=none

### Equipo / miembros
- id: team
- objetivo: Quiero invitar a un compañero.
- actor: user
- UI: /settings — Tab Equipo
- MCP: (sin tools) — Sin tools de equipo por MCP.
- REST: no aplica
- resultado: Miembro invitado / rol gestionado.
- disponibilidad: ui=ok, mcp=pending, rest=none

### Actividad del agente (audit trail MCP)
- id: mcp-activity
- objetivo: ¿Qué ha hecho mi agente?
- actor: user
- UI: /settings — Tab Actividad MCP
- MCP: (sin tools) — Cada acción del MCP queda registrada en mcp_audit y se muestra aquí.
- REST: no aplica
- resultado: Historial: quién, qué tool, cuándo, ok/error.
- disponibilidad: ui=ok, mcp=none, rest=none

## Destinatario

### Baja / centro de preferencias
- id: unsubscribe
- objetivo: El destinatario quiere darse de baja.
- actor: recipient
- UI: /unsubscribe/{token} — Gestionar suscripción a temas
- MCP: (sin tools) — {{unsubscribe_url}} se inyecta por contacto en cada envío.
- REST: no aplica
- resultado: El contacto queda dado de baja / ajusta sus temas; deja de recibir.
- disponibilidad: ui=ok, mcp=none, rest=none