Postari

Envía un correo transaccional 1-a-1 (cotización, recibo, bienvenida, recordatorio) a UNA dirección, usando una plantilla y variables. Síncrono. Requiere scope `send`.

Crea o actualiza (upsert) un contacto/suscriptor. Si ya existe, lo actualiza sin duplicar.

Busca un contacto por su correo y devuelve sus datos, estado, etiquetas e historial básico. Si está rebotado trae `bounce: {tipo, subtipo, fecha, motivo, dominio_sugerido}` (tipo permanente o temporal; motivo rebote_permanente, rebote_temporal_repetido, rebote_temporal o rebote_sin_evento; dominio_sugerido si la dirección parece mal escrita, p. ej. gmail.co → gmail.com); si no, `bounce: null`.

Lista contactos paginados (más recientes primero, cursor keyset). Filtros: status (active|unsubscribed|bounced|complained), list_id (membresías físicas: una lista inteligente devuelve 0 filas; su tamaño está en list_lists (active_count / total_count) o en GET /api/v1/lists/{id}/count) y tag = nombre EXACTO de una etiqueta del catálogo (contact_tags, la misma fuente que /etiquetas). Desde el 3-oct-2026 tag ya no mira las etiquetas importadas (imported_tags): cada fila trae `tags` (importadas, como siempre) y `catalog_tags` (las del catálogo, las que filtra tag). include_count:true añade total_count; si el conteo no se puede hacer responde 503 count_unavailable, nunca 0.

Actualiza datos de un contacto existente (nombre, país, teléfono, etiquetas). Solo envía esos campos: no cambia su estado de suscripción. Para devolver a alguien que salió por un rebote usa reactivate_bounced_subscriber. Quien se dio de baja o marcó spam solo vuelve por decisión propia (centro de preferencias del pie de los correos); un agente no puede resuscribirlo: el PUT /api/v1/subscribers/{email} con confirmar_resuscripcion:true es solo para una persona con su llave, queda auditado y desde el puente MCP responde 403 resuscripcion_no_disponible_para_agentes.

Devuelve a tus envíos a un contacto que salió por un rebote TEMPORAL suelto (buzón lleno, servidor ocupado). Solo funciona si el rebote fue temporal, el dominio no está bloqueado ni mal escrito (gmail.co, hormail.com: corrige la dirección; el 409 trae dominio_sugerido) y no se dio de baja ni marcó spam; si no, responde 409 con el motivo (por ejemplo, rebote definitivo: la dirección no existe). No reanuda flujos viejos ni envía la bienvenida. Úsalo en vez de update_subscriber con status "active".

Saca de circulación a los contactos activos que tienen un rebote PERMANENTE (la dirección no existe) o 3 rebotes temporales seguidos sin ninguna señal de vida entre medio (ni entregado, ni abierto, ni clic). Un rebote temporal suelto, como un buzón lleno, nunca saca a nadie. Deja escrito el motivo en el contacto. Sin `aplicar:true` solo devuelve el recuento por motivo, no cambia nada.

Lista todas las listas de contactos con su tamaño: active_count = contactos ACTIVOS (a quienes les llega un envío) y total_count = todas las membresías (cualquier estado), de list_sizes_v1, la misma fuente que la app. Una lista inteligente se mide evaluando su filtro (hoy no se envía a listas inteligentes); size_ok false = no se pudo medir y los conteos vienen en null. contacts_count es un alias deprecado de total_count.

Takes no parameters.

Crea una nueva lista de contactos.

Añade un contacto (por email o contact_id) a una lista.

Añade o quita una etiqueta a varios contactos (por emails o contact_ids).

Mete un contacto (por email o contact_id) en un flujo automático para que reciba esa secuencia.

Métricas globales de la cuenta (enviados, entregados, abrieron, hicieron clic, bajas, rebotes, contactos nuevos) en un rango de días de la zona horaria de la cuenta, ambos incluidos; la cohorte es el día de ENVÍO de cada correo, la misma fuente que /metricas. avg_open_rate y avg_click_rate en % con 2 decimales sobre ENTREGADOS (avg_*_rate_fraction: alias deprecados en fracción). Si hay días aún sin calcular responde 503 metrics_recalculating: reintenta, nunca son sumas parciales. Rebote separado: bounced_hard / bounce_rate_hard (definitivo, el que se vigila) y bounced_soft / bounce_rate_soft (temporal), en % sobre enviados (bounce_rates_base: "sent"); null si el período no tiene el tipo medido, nunca un 0 inventado. total_bounces = definitivos + temporales. Ojo: en la ficha de campaña (get_campaign_stats) el mismo dato se llama bounce_hard_rate.

Lista las campañas/correos del tenant con sus métricas (metrics.*, desde los contadores que mantiene el reconciliador: durante un envío pueden ir unos minutos detrás de get_campaign_stats). En este listado opened_total, clicked_total, clicked_system, delivered_confirmed, failed, bounced_hard, bounced_soft y bounce_hard_rate llegan en null (los contadores no los guardan; null = no medido, no 0): pídelos a get_campaign_stats. audience_count = «¿a cuántos?»: si ya empezó, la foto del envío; en borrador o programada, los ACTIVOS de la lista hoy ANTES del filtro guardado (audience_basis "list_active_before_filters"); el neto exacto lo da get_campaign_audience. Filtrable por estado (draft, scheduled, sending, sent). Definiciones: enviados = correos con sent_at; entregados = enviados − rebotados; abrieron = correos con apertura (píxel, webhook o clic); clics únicos = correos con clic en un enlace de contenido (baja, preferencias y pie aparte en clicked_system). Tasas en % con 2 decimales: entrega y rebote sobre ENVIADOS; apertura, clic, bajas y quejas sobre ENTREGADOS (rate_base "delivered"); ctor = clics únicos / abrieron. null = sin denominador, nunca 0 inventado. *_fraction son alias heredados en fracción 0-1 (deprecados).

Métricas reales de una campaña leídas de los eventos en vivo: enviados, entregados, abrieron (únicos y aperturas registradas), clics únicos y registrados, clics de sistema, rebotes (bounce_hard_rate = definitivo, el que se vigila), bajas, quejas, ingresos USD atribuidos (ventas con clic o, sin clic, apertura de este correo antes de comprar; si la persona solo lo recibió la venta es «influida» y NO suma) y by_link (clics de contenido por URL). maturity: sending/paused = parcial, settling = enviada hace menos de 24 h. stale true = la lectura falló y las cifras no son de fiar. Definiciones: enviados = correos con sent_at; entregados = enviados − rebotados; abrieron = correos con apertura (píxel, webhook o clic); clics únicos = correos con clic en un enlace de contenido (baja, preferencias y pie aparte en clicked_system). Tasas en % con 2 decimales: entrega y rebote sobre ENVIADOS; apertura, clic, bajas y quejas sobre ENTREGADOS (rate_base "delivered"); ctor = clics únicos / abrieron. null = sin denominador, nunca 0 inventado. *_fraction son alias heredados en fracción 0-1 (deprecados).

AGÉNTICA · Lanza una campaña de correo COMPLETA desde un brief en lenguaje natural. Postari GENERA el correo (asunto + diseño con la voz y el color de marca del tenant), lo arma sobre una lista y devuelve un BORRADOR con preview (preview_html). Por defecto NO envía: para enviar de verdad, vuelve a llamar con los mismos campos + confirm_send:true (o scheduled_at para agendar). Es la forma de "dile el objetivo y Postari lo logra". Requiere scope `write` (borrador) o `send` (enviar).

Diagnóstico de ENTREGABILIDAD de la cuenta (últimos 28 días): rebotes, quejas de spam, aperturas y salud del dominio (DNS). Devuelve un veredicto (sano/a_vigilar/en_riesgo) + acciones priorizadas. El rebote que se juzga (`bounce_rate`) es el DEFINITIVO; el temporal (buzón lleno) va aparte en `bounce_rate_temporal`. Tasas en % con 2 decimales: rebotes y quejas sobre ENVIADOS (umbrales sanos <2 % y <0,1 %); open_rate sobre ENTREGADOS, como account_stats. Úsalo antes de un envío grande o si los correos no llegan.

Takes no parameters.

Transparencia "qué hizo la IA": lista las acciones de la cuenta originadas por un agente/IA (chat Atelier, API de agente, A2A) — qué se hizo, sobre qué y cuándo. Para auditar lo que un agente ejecutó.

Crea un LANZAMIENTO (curso, infoproducto, evento…) con sus etapas: es la unidad que agrupa los correos de una campaña con fechas. Si no pasas `stages` y el tipo es curso/infoproducto, siembra 8 etapas estándar (lead magnet → webinar → apertura de carrito → cierre).

Lista los lanzamientos de la cuenta, con cuántas etapas tiene cada uno y cuántas ya están conectadas a un correo.

Un lanzamiento con sus etapas y las MÉTRICAS REALES de cada una (enviados, entregados, abrieron, clics únicos, bajas, ingresos USD atribuidos por clic o apertura, sin las ventas solo «influidas») más el total; cada campaña se suma una sola vez. stages_sent de stages_total = etapas ya enviadas. metrics null en una etapa = todavía no tiene correo (no es 0). Es la forma de saber cómo va un lanzamiento. Definiciones: enviados = correos con sent_at; entregados = enviados − rebotados; abrieron = correos con apertura (píxel, webhook o clic); clics únicos = correos con clic en un enlace de contenido (baja, preferencias y pie aparte en clicked_system). Tasas en % con 2 decimales: entrega y rebote sobre ENVIADOS; apertura, clic, bajas y quejas sobre ENTREGADOS (rate_base "delivered"); ctor = clics únicos / abrieron. null = sin denominador, nunca 0 inventado. *_fraction son alias heredados en fracción 0-1 (deprecados).

Conecta un correo YA ESCRITO a una etapa del lanzamiento (o lo desconecta con campaign_id null). Sin esto la etapa no mide nada: sus KPIs dependen de este vínculo. También sirve para cambiar título, fecha o estado de la etapa.

Crea una automatización. NACE EN BORRADOR Y DESARMADA: no envía nada hasta que se pruebe, se active y se arme a propósito. El `graph` es el mismo formato que devuelve get_flow.

Edita una automatización: nombre, disparador, pasos (graph) o estado. NO sirve para armar (eso es arm_flow, que exige confirmación); sí para DESARMAR con armed:false.

Prueba una automatización enviándola de verdad a UN miembro de la cuenta (por defecto el dueño). Es OBLIGATORIO antes de armar. No se puede usar para mandar correo a terceros: to_email tiene que ser de un miembro.

Pone la automatización en servicio (status active) o la pausa con paused:true. OJO: activar NO hace que envíe — para eso hace falta armarla (arm_flow).

ARMA la automatización: a partir de aquí envía correos REALES sola. Exige confirm:"ARMAR ENVIOS" literal, haber probado el flujo antes, y que la cuenta permita envíos por agente. NO es retroactivo: solo entra quien cumpla el disparador de ahora en adelante.

Los correos de una automatización, cada uno con su node_id, su asunto y su URL propia para compartir con el cliente. Antes estos correos no tenían dirección: vivían enterrados en el flujo.

Edita UN correo de una automatización (asunto, preheader, bloques o etiqueta) sin tocar el resto del flujo. Más seguro que reescribir el graph entero.

Crea un formulario de captación y devuelve su URL pública y su código para embeber. Si no pasas campos, lleva uno de correo.

Lista los formularios con sus KPIs. El número de cada formulario es primary_count en la unidad primary_unit: people = personas distintas (correo normalizado, sin papelera) en un formulario de captura; submissions = respuestas en una encuesta (is_survey true: una persona puede responder varias veces). people = personas distintas; submissions = envíos sin papelera (filas, repeticiones incluidas: NO es el número del formulario de captura); views = cargas del formulario (1 por navegador cada 24 h); views_measured false = la página que envía las altas no avisa de las visitas; conversion_rate = primary_count / views en % con 1 decimal (null si las vistas no están medidas). Los mismos números que la app.

Un formulario con sus campos y sus KPIs recontados en vivo (form_kpis_v2): primary_count en primary_unit (people en captura, submissions en encuesta), people, submissions (envíos sin papelera), views, views_measured y conversion_rate (primary_count / views, % con 1 decimal, null si las vistas no están medidas). Mismas definiciones que list_forms. Si la lectura falla responde 503 metrics_unavailable (nunca un número sin avisar).

Edita un formulario: título, campos, lista donde caen las altas, doble opt-in, mensaje de gracias o activarlo/desactivarlo.

Crea un segmento: una regla de "quién entra" que se recalcula sola. Es lo que se usa para segmentar un lanzamiento sin duplicar listas.

Crea una plantilla propia de la cuenta, opcionalmente duplicando una del catálogo con from_template_id. Las del catálogo son compartidas y no se editan.

Crea una etiqueta (idempotente: si ya existe devuelve la que hay, no la duplica).

Crea una página de aterrizaje y devuelve su URL pública. `kind`: blocks (bloques de Postari) · code (HTML propio) · ai (desde un prompt) · iframe · external_url. Conéctale un formulario con form_id para que capte suscriptores.

Lista las páginas de aterrizaje con sus visitas, conversiones y tasa de conversión (conversion_rate = conversiones / visitas en % con 2 decimales y tope 100; null si aún no hubo visitas: no medible, no es 0 · cambio de contrato del 3-oct-2026, antes devolvía 0).

Edita una página de aterrizaje: contenido, slug, formulario conectado o activarla/desactivarla. Cambiar el slug rompe la URL que ya se haya compartido (la respuesta avisa).

Define A QUIÉN se le manda un correo y a quién NO: excluir por etiqueta, por lista entera o por haber recibido otra campaña. Devuelve el número REAL de destinatarios para confirmar antes de enviar. Si alguna referencia no existe, falla con 400 en vez de guardar a medias.

¿A cuánta gente le va a llegar este correo? Devuelve los destinatarios REALES aplicando el filtro guardado, por el mismo camino que el envío: base = activos de la lista hoy, excluidos = los que quita el filtro, audience_live_total = el público de HOY. Si ya empezó a enviarse trae además recipients_snapshot (la foto del primer tick), excluded_on_send (tope de frecuencia y dominios bloqueados) y remaining_to_send. total_recipients es un alias deprecado de audience_live_total.