Servidor MCP de Marketing
Conecta tu asistente de IA a las campañas, listas, plantillas, automatizaciones e informes de Marketing, con sus herramientas, scopes y reglas de uso.
Actualizado el . 26 min de lectura
Incluido en los planes Profesional y Avanzado. Hasta 10.000 correos de campaña por ciclo en Profesional y 25.000 en Avanzado. Ver precios
El servidor MCP de Marketing (utilia-marketing) conecta tu asistente de IA con el marketing por correo de UTILIA OS: campañas, listas y segmentos, plantillas, automatizaciones, pruebas A/B, bajas y supresiones, informes y entregabilidad. Necesitas un token OAuth o una clave personal emitidos para este servidor.
| Dato | Valor |
|---|---|
| Dirección | https://os.utilia.ai/api/mcp/marketing |
| Nombre en «Conecta tu IA» | Marketing |
| Metadatos de descubrimiento | GET /.well-known/mcp-marketing.json |
| Versiones del protocolo | 2025-11-25 y 2025-06-18, negociadas en initialize |
Cómo se conecta
Se conecta igual que los demás servidores: desde Ajustes › Integraciones › Conecta tu IA, necesitas entrar con tu cuenta autorizas tu cliente MCP con OAuth o generas una clave personal para este servidor. El proceso completo está en Primeros pasos con MCP.
Cada token se emite para /api/mcp/marketing y solo sirve ahí: un token de Marketing no vale para el CRM, Finanzas ni Gestión de proyectos, y al revés tampoco.
Un token de este servidor puede llevar scopes marketing:*, org:email-senders:*, los de lectura del CRM (crm:*:view), los del plan (org:plan:*), los de avisos (org:notifications:*) y los tres de tickets propios (support:tickets:view, :create y :update). Para entrar hace falta al menos uno marketing:*, uno org:email-senders:* o uno del plan. Los metadatos de descubrimiento anuncian también los scopes crm:*:view, porque la previsualización de un segmento del CRM los necesita, pero un token con solo scopes del CRM no entra.
Las cuatro comprobaciones
Cada operación pasa cuatro comprobaciones, y basta con que falle una para que se deniegue:
Qué comprueba el servidor de Marketing
El token
Token de este servidor
Tiene que haberse emitido para /api/mcp/marketing.Si no: error JSON-RPC -32600, sin mirar nada más.
Tu organización
Marketing en el plan
«Conecta tu IA» muestra el área con candado.Si no: se rechaza con un mensaje que lo explica; ningún permiso la abre.
El token
Scope de la operación
Una escritura nunca se ejecuta con un scope de solo lectura.Si no: se deniega, aunque la herramienta sea visible.
Tu usuario
Permiso de Marketing
El resultado se recorta a tu alcance de filas.Si no: «Permiso denegado. Requiere: ...».
Herramientas
El servidor publica 15 herramientas propias y 5 compartidas con otros servidores.
| Herramienta | Para qué sirve |
|---|---|
marketing_campaigns | Campañas: crear, editar, duplicar, programar, enviar y cancelar; sus destinatarios; qué hizo la audiencia, y el segundo intento a quien no la abrió. |
marketing_lists | Listas y segmentos, incluidos los que leen el CRM; sus suscriptores con su interés, y el apartado de inactivos. |
marketing_templates | Plantillas de correo. |
marketing_automations | Automatizaciones de correo: disparadores, pasos y estadísticas. |
marketing_ab_testing | Pruebas A/B y elección de la variante ganadora. |
marketing_suppressions | Bajas, rebotes y supresiones: a quién no se puede escribir. |
marketing_reports | Informes y negocio originado: resultados por campaña, clics por destino, quejas, qué enlace se pulsa, con qué se lee, agregados del periodo y atribución. |
marketing_deliverability | Entregabilidad: reputación, rebotes, quejas, política de quejas y límite de frecuencia. |
marketing_bounce_settings | Procesamiento de rebotes por IMAP y por webhook del proveedor. |
marketing_tracking_settings | Medición del origen: las etiquetas que se añaden a los enlaces y el identificador del destinatario. |
email_tracking_domains | El subdominio propio por el que vuelve el clic. |
marketing_audience_search | Búsqueda de audiencia (contactos, leads y suscriptores) para preparar un envío. |
marketing_recipients_preview | Los destinatarios que saldrían de una selección, antes de enviar. |
marketing_overview | Vista de conjunto del aplicativo en una llamada. |
marketing_assets | Imágenes para los correos. |
email_sender_domains | Dominios de envío y su verificación SPF, DKIM y DMARC. También en el servidor del CRM. |
email_sending_routes | Ruta de envío: por dónde sale el correo. También en el servidor del CRM. |
org_plan | Plan, consumo de IA, peticiones de ampliación y reserva de una llamada con UTILIA. En todos los servidores. |
my_tickets | Reportar y seguir tus tickets de soporte. En todos los servidores. |
notifications | Tus avisos y tus preferencias de aviso. En todos los servidores. |
marketing_audience_search y marketing_recipients_preview devuelven datos personales del CRM (nombre, correo, empresa y motivo de exclusión, incluida la razón de una baja), así que solo los ve un token que ya pueda ver campañas o listas.
Los SDK envuelven ocho herramientas en sdk.mcp.marketing: reports, campaigns, lists, deliverability, trackingSettings (marketing_tracking_settings), trackingDomains (email_tracking_domains), bounceSettings y sendingRoutes (email_sending_routes), con los mismos nombres en snake_case en Python. El resto se invoca por JSON-RPC, como en los ejemplos de esta página. Qué cuenta cada cifra de marketing_reports se explica en Definiciones de las métricas de Marketing.
Scopes
El servidor tiene 22 scopes propios y 3 conjuntos. Cada scope corresponde a un permiso de la aplicación: el token nunca concede más de lo que tienes.
| Scope | Qué autoriza |
|---|---|
marketing:campaigns:view | Ver campañas y sus destinatarios. |
marketing:campaigns:create, :update, :delete | Crear, modificar y borrar campañas. |
marketing:campaigns:send | Enviar campañas y lanzar y confirmar la comprobación en buzones. Es irreversible y no está en marketing:write. |
marketing:campaigns:schedule | Programar el envío de una campaña. No está en marketing:write. |
marketing:recipients:detail:view | Ver el detalle técnico de cada destinatario: aparato, programa de correo y país. |
marketing:lists:view y :manage | Ver y gestionar listas, segmentos y suscriptores. |
marketing:templates:view, :create, :update, :delete | Gestionar plantillas. |
marketing:automations:view y :manage | Ver y gestionar automatizaciones. |
marketing:suppressions:view y :manage | Ver y gestionar bajas, rebotes y supresiones. |
marketing:reports:view | Informes, analítica y negocio originado. |
marketing:deliverability:view y :manage | Ver y configurar la entregabilidad, el procesamiento de rebotes y el subdominio de medición. |
marketing:tracking:manage | Consultar y cambiar la medición del origen. No está en marketing:write, porque enciende el identificador del destinatario, que es tratamiento de datos personales. |
marketing:ab-testing | Crear pruebas A/B y elegir la variante ganadora. No está en marketing:read ni en marketing:write. |
Transversales que admite el token: org:email-senders:view y :manage (dominios de envío), org:plan:view, :request y :manage_requests (plan y llamadas), org:notifications:view y :manage (avisos) y los tres de tickets propios.
| Conjunto | Qué incluye |
|---|---|
marketing:read | Todos los marketing:*:view, org:email-senders:view y org:plan:view. |
marketing:write | Las escrituras de contenido (:create, :update, :manage). No incluye enviar, programar, marketing:tracking:manage ni marketing:ab-testing, ni tampoco las lecturas: pídelo junto a marketing:read. |
marketing:full | Todos los marketing:* y org:email-senders:*, con los del plan. |
Desde el 5 de septiembre de 2026, marketing:write ya no envía
marketing:campaigns:send y marketing:campaigns:schedule salieron ese día de marketing:write, cuyo texto de autorización siempre dijo «no incluye envío». Una integración que enviaba o programaba gracias a ese conjunto necesita volver a autorizarse pidiendo los dos scopes por su nombre, o marketing:full. No hubo periodo de gracia; los tokens que ya llevaban los dos scopes no se ven afectados.
marketing:recipients:detail:view recorta campos, no operaciones: sin él, list_recipients responde igual pero sin deviceType, emailClient ni country, y con recipientDetailIncluded: false. Además del scope, exige el permiso EMAIL_MARKETING_VIEW_RECIPIENT_DETAIL.
Medición del origen y negocio por campaña
Dos bloques: de dónde vienen las visitas que llegan desde tus correos y qué negocio salió de cada campaña.
marketing_tracking_settings
Configuración de medición de la organización, con tres operaciones.
| Operación | Qué hace | Permiso | Scope |
|---|---|---|---|
get | Devuelve la configuración, con capabilityActive y canManage ya resueltos. | EMAIL_MARKETING_VIEW o EMAIL_MARKETING_TRACKING_MANAGE | marketing:tracking:manage o marketing:campaigns:view |
update | Cambia utmEnabled, utmTemplate, recipientTokenEnabled y recipientTokenTtlDays. | EMAIL_MARKETING_TRACKING_MANAGE | marketing:tracking:manage |
preview_link | Cómo quedaría un enlace concreto. | EMAIL_MARKETING_VIEW | marketing:tracking:manage o marketing:campaigns:view |
preview_linkno escribe ni firma nada y no emite ningún identificador de destinatario real: en su lugar devuelve un marcador.utmTemplateadmite cinco tokens y ninguno más:{{campaign.name}},{{campaign.id}},{{campaign.type}},{{variant}}y{{date}}. Uno inventado se rechaza al validar, porque si llegara al correo se borraría al enviarlo y el enlace saldría roto sin aviso.utm_termse deja vacío siempre. Significa «término de búsqueda de pago»; rellenarlo en un correo sería meter un dato falso en la analítica de quien lo recibe.utm_contentsolo se rellena en pruebas A/B, con la etiqueta de la variante.- Los parámetros de origen no dependen del plan. Sin ellos, las visitas que llegan de tus correos aparecerían como tráfico directo en tu analítica.
El identificador del destinatario es tratamiento de datos personales. recipientTokenEnabled hace que cada enlace lleve un código firmado y con caducidad (entre 7 y 180 días, 90 por defecto) que permite saber de qué campaña venía quien luego rellena uno de tus formularios.
No contiene el correo, ni el nombre, ni ningún identificador de ficha. No rellena ningún campo del formulario —ese es justo el camino por el que un correo reenviado filtraría la dirección de otra persona—, no sirve para darse de baja ni para autenticarse, y no vale en otra organización. Solo se aplica a la persona si el correo que escribe en el formulario coincide con el del envío; si no coincide, la atribución se queda en la campaña y nunca se guarda el identificador del envío.
Nace apagado, también en las organizaciones nuevas, y encenderlo exige la capacidad Negocio por campaña. La comprobación de plan se hace solo cuando esa llamada trae recipientTokenEnabled: apagar los parámetros de origen no depende del plan. Cada cambio queda registrado en el histórico de auditoría con quién y cuándo. Antes de encenderlo, amplía la información del artículo 13 del RGPD que das a quien rellena el formulario.
Los tres campos de medición de una campaña
create y update de marketing_campaigns aceptan tres campos de medición:
| Campo | Qué hace |
|---|---|
utmMode | RESPECT añade los parámetros que falten y no toca los que el enlace ya traiga (se decide parámetro a parámetro); OFF deja esa campaña sin parámetros de origen. |
utmParams | Valores propios de esa campaña para source, medium, campaign, term y content. |
trackingIdentityEnabled | Si los enlaces de esa campaña llevan el identificador del destinatario. |
Los tres admiten null, y null significa «hereda de la organización», que no es lo mismo que no enviar el campo: no enviarlo deja el valor como estaba. trackingIdentityEnabled solo puede restar: un true de campaña no enciende nada si la organización lo tiene apagado o si el plan no incluye la capacidad.
La operación get de marketing_campaigns devuelve además el bloque tracking con la configuración ya resuelta y de dónde sale cada valor (campaign, organization o default), para que no tengas que calcular la herencia.
Negocio originado: tres operaciones de marketing_reports
| Operación | Qué devuelve | Permiso | Capacidad |
|---|---|---|---|
campaign_attribution | Negocio originado por UNA campaña. Con breakdown (LEAD, OPPORTUNITY, BUDGET, INVOICE o COLLECTION), la lista paginada de esas entidades. | EMAIL_MARKETING_ANALYTICS | Negocio por campaña |
attribution_summary | El mismo agregado para todo un periodo. | EMAIL_MARKETING_ANALYTICS | Negocio por campaña |
entity_origin | La vista inversa: de qué campaña vino una oportunidad (OPPORTUNITY) o un cliente (CLIENT). | EMAIL_MARKETING_VIEW más el de la ficha | — |
top_campaigns admite además las métricas CONVERSIONS (oportunidades originadas, no ventas cerradas), REVENUE_ISSUED y REVENUE_COLLECTED.
Los importes no viajan por este servidor. Un token de /api/mcp/marketing no puede llevar scopes de Finanzas, así que por este carril llegan los recuentos y el bloque de dinero se declara ausente en excludedBlocks con reason: "missing_scope". No hay ningún bloque de tasas de conversión: el servidor no lo emite, y calcularlas dividiendo dos de esos recuentos es una cuenta que nadie ha respaldado.
Eso no es un cero, porque un cero afirmaría que no hubo negocio: presenta el motivo, no la cifra. Las cifras están en la pantalla de Marketing del producto y en GET /api/email-marketing/attribution/....
Por el mismo motivo, la vista inversa de una factura no existe por MCP: su origen comercial está en GET /api/finance/invoices/:id/commercial-origin.
Las facturas creadas desde fuera no cuentan. La API externa v1 de facturas (sdk.invoices.create(), POST /external/v1/invoices) no admite opportunityId ni projectId. Una factura emitida por una integración externa nace sin vínculo comercial, así que no aparecerá en el negocio originado por ninguna campaña.
Si facturas desde fuera y quieres que ese dinero cuente, crea la factura desde el producto, desde un presupuesto, desde una suscripción o por MCP con crm_invoices, que sí acepta opportunityId.
Cómo leer las cifras sin decir una falsedad
- Facturado y cobrado son dos cifras distintas, cada una agregada por su propia fecha. Cobrado mayor que facturado es un estado legítimo por desfase de periodo, y su cociente no es un porcentaje de nada: no los dividas.
- Un presupuesto no es un ingreso. El negocio en presupuestos firmados y aún no facturados viaja aparte, en
amounts.budgeted. - Los recuentos de factura son dos y no se pueden confundir.
counts.invoicesIssuedson las facturas emitidas;counts.invoicesCollected, las facturas distintas con algún cobro registrado. Ycounts.collectionscuenta COBROS, no facturas: una factura con tres pagos parciales suma uno en la segunda cifra y tres en la tercera. No existe ningúncounts.invoicesa secas. - Con
breakdown, la paginación viaja DENTRO deentities(entities.total,entities.page,entities.limit), no en la raíz de la respuesta. - Las monedas viajan desglosadas y jamás sumadas. No hay conversión de divisa.
reconstructed: truesignifica que la cifra es un suelo, nunca un total. Hay negocio anterior al corte de medición que ninguna regla honesta puede reconstruir. Di «al menos X», no «esta campaña generó X».measuredSincedice desde cuándo hay medición. Un periodo anterior no devuelve ceros: devuelve la fecha. «Todavía no lo medíamos» y «no hubo negocio» son dos afirmaciones distintas.scopeLimited: trueavisa de que el alcance de filas de quien pregunta recorta lo agregado: otra persona con más alcance vería cifras mayores sobre la misma campaña.
email_tracking_domains: el dominio por el que vuelve el clic
Los enlaces de una campaña pasan por UTILIA para poder contar los clics, así que por defecto apuntan a un dominio nuestro aunque el correo lo firme el dominio del cliente. Esta herramienta permite que apunten a un subdominio de tu organización, como enlaces.tuempresa.com, lo que mejora la entregabilidad.
No la confundas con sus dos hermanas, que responden preguntas distintas:
| Herramienta | Qué responde |
|---|---|
email_sender_domains | «¿Está bien publicado quién firma mis correos?» (SPF, DKIM, DMARC) |
email_sending_routes | «¿Por dónde sale el correo?» |
email_tracking_domains | «¿Por dónde vuelve el clic?» |
Ocho operaciones:
| Operación | Qué hace | Permiso | Scope |
|---|---|---|---|
list | Dominios de medición de la organización. Como mucho hay uno vivo. | EMAIL_MARKETING_VIEW | marketing:deliverability:view o marketing:campaigns:view |
get | Un dominio con su estado, la caducidad del certificado y hasta cuándo se sirve. | EMAIL_MARKETING_VIEW | marketing:deliverability:view o marketing:campaigns:view |
get_setup_instructions | El registro CNAME que hay que publicar. | EMAIL_MARKETING_DELIVERABILITY_MANAGE u ORGANIZATION_EMAIL_SENDER_MANAGE | marketing:deliverability:view |
create | Da de alta el subdominio. | Los dos de gestión | marketing:deliverability:manage |
verify | Comprueba el CNAME contra el DNS real. Exige confirm: true. | Los dos de gestión | marketing:deliverability:manage |
set_emission | Enciende o apaga la medición por ese dominio. | Los dos de gestión | marketing:deliverability:manage |
retry_certificate | Vuelve a pedir el certificado ahora, sin esperar turno. | Los dos de gestión | marketing:deliverability:manage |
retire | Programa el fin del servicio. Exige confirm: true. | Los dos de gestión | marketing:deliverability:manage |
Estados del subdominio, tal como los devuelven list y get en status:
Estados del subdominio de medición
Pendiente
PENDING
Dado de alta con create; el CNAME todavía no se ha visto.Se llega desde Pendiente cuando: verify o la comprobación periódica
Comprobando
VERIFYING
Hay una comprobación del CNAME en curso.Se llega desde Comprobando cuando: 7 días sin verificarse nunca
Fallido
FAILED
Los enlaces nuevos vuelven al dominio de UTILIA OS.
Se llega desde Comprobando cuando: El CNAME apunta donde debe
Verificado
VERIFIED
Solo en este estado, y con set_emission encendido, salen los enlaces nuevos por tu subdominio.Se llega desde Verificado cuando: retire con confirm: true
Retirado
RETIRED
Estado final
Se conserva y sigue atendiendo los enlaces ya enviados; serveUntil marca 90 días de servicio.
Otras transiciones
- Comprobando pasa a Pendiente: El CNAME aún no aparece y no ha vencido el plazo.
- Verificado pasa a Fallido: 14 días sin señal positiva después de haberse verificado.
- Fallido pasa a Comprobando: Vuelves a comprobarlo con verify cuando el registro está publicado.
La regla que manda sobre todas: un enlace ya enviado no se puede romper
Un correo entregado lleva su dominio escrito dentro y no hay forma de reescribirlo. De ahí tres consecuencias que conviene tener claras antes de automatizar nada:
retireno borra nada. Programa el fin del servicio y devuelve enserveUntilla fecha hasta la que ese subdominio sigue atendiendo los enlaces de los correos ya entregados. Enseña esa fecha y lo único que se pide a cambio: no retirar el CNAME antes. Ninguna operación de esta herramienta destruye nada.createno empieza a medir. El alta solo abre el proceso. Decir «ya se mide por tu dominio» justo después de crearlo es falso: falta publicar el CNAME, comprobarlo, esperar al certificado y encender la medición conset_emission.set_emissionsolo afecta a los envíos nuevos. Encenderla exige que el dominio esté sirviendo y con una prueba de extremo a extremo reciente; apagarla no tiene condiciones y es inmediata. Es la palanca reversible.
Si se retira el CNAME, los enlaces de los correos ya enviados dejan de funcionar en 90 días como mucho. No es «se pierde una métrica»: cuando el certificado caduca por no poder renovarse, quien pulsa un enlace de un correo ya recibido ve un aviso de seguridad del navegador y no llega a tu página. certificateExpiresAt trae la fecha exacta, y es el dato que hay que poner delante en cuanto lastCheckStatus deja de ser OK. Si se vuelve a publicar el registro antes de esa fecha, se recupera solo.
- Solo se acepta CNAME. Un registro
Aa nuestra dirección funciona hoy y deja de funcionar el día que cambiemos de servidor, sin avisar a nadie. Si se detecta uno, la comprobación lo dice con ese motivo en vez de darlo por bueno. - Tiene que ser un subdominio (tres etiquetas o más). Medir en la raíz obligaría a apuntar aquí el dominio entero.
- Las tres lecturas no dependen del plan: aunque cambies de plan, puedes seguir viendo hasta cuándo se atienden los enlaces de tus correos ya enviados.
- Cuatro de las ocho operaciones exigen capacidad de plan, y hacen falta las dos del lote de medición: «Analítica avanzada de Marketing» y «Negocio por campaña». Son las que levantan infraestructura:
create,verify,set_emissionyretry_certificate. Sin ellas, la respuesta dice qué plan las incluye.retireno las exige, como las tres lecturas: es la salida.
La guía de uso, con los plazos y lo que pasa si se retira el registro: Enlaces con tu propio dominio.
Tres excepciones al aplicativo Marketing
Son deliberadas:
marketing_campaigns: convert_clicksyconversion_candidatesexigen además el aplicativo CRM. Crean leads y oportunidades, o describen el estado del CRM para quienes pulsaron. Cruzan de Marketing al CRM, así que una organización con Marketing y sin CRM las recibe denegadas.marketing_campaigns: sending_quotano exige Marketing. El cupo de correos suma los envíos de campaña y los pasos de envío de las automatizaciones del CRM, así que una organización sin Marketing consume el mismo cupo y está sujeta al mismo tope: cerrarle la lectura la dejaría ciega justo a ella.email_sending_routestampoco exige Marketing. La ruta de envío gobierna también las facturas, los presupuestos, el portal y los avisos, que existen en todos los planes. Su puerta comercial es la capacidad transversal de ruta de envío propia, no el aplicativo Marketing.email_sender_domains, en cambio, sí exige Marketing.
Ejemplo de llamada
El servidor habla JSON-RPC 2.0 sobre HTTP. Con el token ya obtenido, listar las herramientas disponibles y llamar a una es una petición corriente.
# 1. Qué herramientas ve este token
curl -sS https://os.utilia.ai/api/mcp/marketing \
-H "Authorization: Bearer $UTILIA_MCP_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# 2. Resultados de una campaña
curl -sS https://os.utilia.ai/api/mcp/marketing \
-H "Authorization: Bearer $UTILIA_MCP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "marketing_reports",
"arguments": { "operation": "campaign_stats", "campaignId": "cmp_123" }
}
}'Qué hizo la audiencia y el segundo intento
Cuatro operaciones de marketing_campaigns (engagement_breakdown, resend_preview, create_resend y list_resends) responden a la pregunta que más se le hace a un asistente de marketing, «¿a quién le llegó y qué hizo?», y a la siguiente, «¿puedo volver a escribirle?».
Los grupos de la audiencia
engagement_breakdown reparte a los destinatarios en siete grupos, en dos niveles: dentro de «Abrieron» (opened) están «Pulsaron» (clicked) y «Abrieron y no pulsaron» (opened_not_clicked), así que sumar los siete da un número que no significa nada. «No abrieron» (not_opened) excluye siempre a quien pulsó: una apertura solo se registra si el programa de correo carga las imágenes, y muchos no lo hacen, mientras que un clic es un hecho.
create_resend solo admite dos de esos grupos. Pedir cualquier otro se rechaza, con el motivo en el mensaje de error:
A quién se puede volver a escribir
create_resend los acepta
Admiten un segundo intento
not_opened) y «Abrieron y no pulsaron» (opened_not_clicked).create_resend los rechaza
No admiten un segundo intento
opened), que incluye a quien pulsó; «Pulsaron» (clicked); «Rebotaron» (bounced); «Se dieron de baja» (unsubscribed); «Se quejaron» (complained), y «Respondieron» (replied), que no está en el desglose pero sí sirve para filtrar. A quien ya pulsó no hay que insistirle, y a los demás no les llega o no se les debe escribir.Ejemplo: un segundo intento a quien no lo abrió
Tres llamadas: mirar qué pasó, ver qué costaría reenviar y crear la campaña hija. Ninguna de las dos primeras cambia nada.
# 1. Qué hizo la audiencia. Gratuito: no exige capacidad de plan.
curl -sS https://os.utilia.ai/api/mcp/marketing \
-H "Authorization: Bearer $UTILIA_MCP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "marketing_campaigns",
"arguments": { "operation": "engagement_breakdown", "id": "cmp_123" }
}
}'
# 2. Qué costaría volver a escribir a quien no lo abrió. NO crea nada.
curl -sS https://os.utilia.ai/api/mcp/marketing \
-H "Authorization: Bearer $UTILIA_MCP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "marketing_campaigns",
"arguments": {
"operation": "resend_preview",
"id": "cmp_123",
"audience": "not_opened"
}
}
}'
# 3. Crear la campaña hija, en borrador. El asunto DEBE ser distinto.
curl -sS https://os.utilia.ai/api/mcp/marketing \
-H "Authorization: Bearer $UTILIA_MCP_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "marketing_campaigns",
"arguments": {
"operation": "create_resend",
"id": "cmp_123",
"audience": "not_opened",
"subject": "Por si se te pasó: novedades de agosto"
}
}
}'Qué depende del plan. engagement_breakdown y list_resends son gratuitos. resend_preview y create_resend, el filtro engagement de list_recipients, el interés de los suscriptores, el apartado de inactivos, link_heatmap y audience_tech forman parte de la capacidad Analítica avanzada de Marketing. Sin ella, la llamada responde con un error en texto que explica qué falta; por MCP no viaja errorCode, así que no lo trates como un fallo técnico.
Quejas por correo no deseado, y qué enlace se pulsa
marketing_reports: complaintsdevuelve las quejas del periodo, agrupadas por campaña o por dominio del destinatario. La tasa llega comonull—nunca como 0— cuando la organización no tiene ninguna vía por la que enterarse, y cuando hay medición es un suelo: solo se cuentan las que el proveedor de envío comunica. Gmail y Yahoo filtran por encima del 0,3 %.marketing_deliverability: get_complaint_policydice qué umbral se aplica y si el arranque de campañas nuevas por el servidor compartido está bloqueado, por qué y hasta cuándo. Es lo que convierte un «no se puede enviar» en una explicación. Un bloqueo se levanta solo en cuanto la tasa baja.marketing_reports: link_heatmapdistingue dos botones que llevan al mismo sitio, que es lo que el desglose por dirección de destino (click_through, gratuito) no puede hacer.marketing_reports: audience_techdesglosa por aparato, programa de correo o país (dos letras, aproximado y de base local). Sale de los clics por defecto: el aparato de una apertura suele ser el del proxy de imágenes del buzón. Con menos de 20 clics no lo presentes.
El detalle técnico de un destinatario se omite, no se deniega. marketing_campaigns: list_recipients devuelve deviceType, emailClient y country solo con el permiso EMAIL_MARKETING_VIEW_RECIPIENT_DETAIL y el scope marketing:recipients:detail:view. Sin ellos, la llamada responde igual, esos tres campos no viajan y llega recipientDetailIncluded: false. Su ausencia significa «no puedo enseñártelo», nunca «no se sabe».
Antes de enviar, durante y después
Estas operaciones permiten preguntar si una campaña está lista sin intentar enviarla, explicar qué pasó con un correo concreto, saber quién ha contestado y dejar constancia de en qué bandeja cayó la prueba.
marketing_campaigns: preflight
Ejecuta en modo diagnóstico las mismas comprobaciones que bloquean al programar y al arrancar, y devuelve la lista entera con su estado. Es de solo lectura: no reserva cupo, no confirma ningún aviso y no autoriza nada.
- Llámalo antes de
sendo deschedule. ConcanSend: falseno envíes: hay algo que bloquea y el envío se rechazaría igual, después de haber tocado el cupo. status: 'unknown'significa que esa comprobación no se ha podido hacer, que no es lo mismo que estar bien.- Lo abren los tres permisos del envío (ver, enviar y programar) en OR: quien solo puede mirar la campaña también necesita entender por qué no sale.
marketing_campaigns: recipient_timeline
El relato de un correo: encolado, intentos, aceptación o rechazo con su causa, exclusión deliberada, rebote, apertura, clic, queja, baja y respuesta. El sendId sale del campo id que viaja dentro de sends[] en cada fila de list_recipients, y también de list_replies.
ACCEPTED no significa que llegara a nadie. Un hito ACCEPTED acredita que el servidor de destino se hizo cargo del mensaje. No dice que llegara a la bandeja de entrada, ni que la persona lo viera. Un hito con metadata.derived se ha reconstruido a partir de las columnas del envío porque es anterior a esta versión, y así se declara en vez de presentarlo como un registro nuevo.
La clave tech (aparato, programa de correo, país y enlace pulsado) viaja solo con el permiso EMAIL_MARKETING_VIEW_RECIPIENT_DETAIL y el scope marketing:recipients:detail:view; techIncluded lo declara.
marketing_campaigns: list_replies
Quién ha contestado, con la marca automatic. Una respuesta con automatic: true la generó una máquina, como un aviso de ausencia: no la cuentes como conversación ni como interés. Un aviso de no entrega no es una respuesta.
Ver que alguien contestó lo gobierna EMAIL_MARKETING_VIEW. Leer lo que dijo es otra cosa: el adelanto del texto (snippet) exige el permiso de interacciones del CRM y el aplicativo CRM en el plan, porque el contenido de un correo no se vuelve más accesible por venir de una campaña. Cuando no viaja, snippetIncluded: false lo dice, y eso no significa que no haya texto.
El pack de comprobación en buzones
Tres operaciones: inbox_check_start manda la prueba de la campaña a hasta
tres buzones propios por el camino real y deja una comprobación pendiente por cada uno; inbox_check_confirm registra lo que una persona ha visto; inbox_checks_list devuelve lo confirmado.
- Consume el mismo freno que el envío de prueba y no gasta correos del plan. Exige
confirm: true. - No concede ningún estado. Que un correo llegue a la bandeja principal solo lo puede confirmar una persona abriendo su buzón, y esa confirmación
caduca a los 90 días (
expired: true) porque las reglas de los buzones cambian. - En la confirmación, todos los campos son opcionales: lo que no se declara queda sin comprobar, que no es ni un aprobado ni un suspenso.
marketing_deliverability: address_check
Tres bloques independientes sobre una dirección o sobre una lista de hasta 500: lo que dice nuestro histórico (baja, rebote, estado del suscriptor), la comprobación técnica del dominio (sintaxis y registros MX o A) y la evidencia de suscripción.
No comprueba que el buzón exista ni que haya autorización. El veredicto NO_BLOCKS significa «no consta ningún impedimento nuestro».
No dice que el buzón exista, ni que la dirección esté bien escrita en el sentido de que alguien la lea, ni que haya autorización para escribirle.
Y hay dos ausencias que no significan lo mismo: consentIncluded: false quiere decir que quien pregunta no tiene permiso para ver la evidencia (hacen falta EMAIL_MARKETING_LISTS_MANAGE y el scope marketing:lists:manage) y entonces la clave consent no viaja en ninguna fila; consent: null sí viaja y quiere decir que no consta ninguna suscripción. Una ficha en el CRM no es una suscripción.
marketing_deliverability: frequency_cap_get y frequency_cap_set
El máximo de correos de campaña que puede recibir la misma dirección en una ventana de días. Nace apagado en todas las organizaciones, así que enabled: false significa que hoy no se excluye a nadie por frecuencia, no que la regla sea infinita. A quien lo supera se le excluye al construir la audiencia con el motivo FREQUENCY_CAP, y eso no es un fallo de envío. Una campaña concreta puede saltárselo desde update con frequencyCapOverride, y hay que explicar por qué.
Leerlo vale con el permiso de ver Marketing; cambiarlo exige el de gestión de entregabilidad, porque decide a cuánta gente deja de llegarle el correo.
marketing_lists: consentimiento, readmisión e importación
| Operación | Qué hace | Permiso |
|---|---|---|
consent_history | Todos los hechos de consentimiento de una persona, del más antiguo al más reciente. Sobrevive a su baja porque se consulta por correo. | EMAIL_MARKETING_LISTS_MANAGE |
resend_confirmation | Reenvía el correo de doble opt-in a quien sigue pendiente. Mientras no confirme, no recibe las campañas de la lista. | EMAIL_MARKETING_EDIT |
reactivate_contact | Borra la baja global de un contacto y le vuelve a permitir recibir correo. Exige confirm: true. | EMAIL_MARKETING_LISTS_MANAGE |
import_preview / import_start / import_status / import_stop / import_rejected | Supervisar una importación de suscriptores. | EMAIL_MARKETING_LISTS_IMPORT (consultar el expediente, EMAIL_MARKETING_VIEW) |
reactivate_contactno esreactivate_subscriber. Aquella devuelve a alguien que se apartó por inactividad dentro de una lista; esta borra la baja global y afecta a todas las comunicaciones. Ninguna de las dos crea consentimiento: si la persona no lo ha dado de nuevo, no le escribas.- El archivo de una importación no se sube por esta vía. Se sube en la pantalla, que devuelve el testigo
previewDataKey, y por integración se recalculan las cifras y se pone en marcha el trabajo con ese testigo. Para dar de alta direcciones que ya tienes a mano estáadd_subscribers, que sigue exigiendoimportDeclaration. import_stopno deshace nada: quien ya entró se queda en la lista y solo se deja de procesar el resto del archivo.import_rejectedexige los dos permisos, importar y exportar: son correos de personas que no están en la lista, y sacarlos del producto es una exportación.
email_sending_routes: header_report y managed_retry
header_reportinspecciona el correo de prueba de una ruta sin enviarlo: firma DKIM con su dominio y selector, cabeceras de baja de un clic, sobre, SPF y DMARC del dominio del remitente, variables sin rellenar y notas en castellano con lo que falta. No sale ni un byte, no consume el freno y no gasta reputación. Nunca devuelve claves privadas ni el secreto.managed_retrysaca la cuenta gestionada por UTILIA de un estado terminal y dispara una sonda de envío real, así que exigeconfirm: true. Si la organización ya envía por su propia ruta, respondesupersededy no toca el transporte de nadie. No devuelve ninguna credencial.
La prueba real (test) devuelve ahora verdicts y headerReport además de ok. ok significa que el servidor de salida aceptó el correo, y nada más: la bandeja de entrada solo la confirma una persona.
marketing_automations: stopOnReply
create y update admiten stopOnReply, encendido por defecto: la secuencia se detiene cuando la persona contesta. Solo cuenta la respuesta humana; una respuesta automática de ausencia no para nada. Necesita algún buzón de correo sincronizado en la organización: sin él no se registran las respuestas y la opción, aunque quede guardada, no puede surtir efecto.
Cifras que cambian de significado
get_stats(enmarketing_reports: campaign_stats) ya no cuenta como «fallidos» los correos que no salieron a propósito. Esos van enexcluded, con su desglose enexcludedByReason. La cifra de fallidos de las campañas ya enviadas bajó por este cambio, y no porque nada se haya arreglado.repliescuenta personas distintas que han contestado, y valenull—nunca cero— cuando la organización no tiene ningún buzón sincronizado del que enterarse.availability.replieslo dice con el motivoNO_MAILBOX_SYNC.list_recipientsadmitefailureCategory(conEXCLUDEDpara el grupo de los excluidos),sendStatusInpara pedir varios resultados a la vez y el segmentorepliedenengagement. Cada fila trae dentro desends[]el ciclo de vida del envío y suid, que es lo que abrerecipient_timeline.listya no devuelve el contenido de cada campaña salvo que pidasincludeContent: true. Veinte campañas con su HTML eran cientos de miles de caracteres para responder «¿qué campañas tengo?». Engetel valor por defecto sigue siendotrue, porque ahí el contenido es lo que se ha ido a buscar.
Conexiones con el resto del ecosistema
Con qué se conecta el servidor de Marketing
Recibe de
CRM
Los segmentos leen contactos y leads; por eso se anuncian los scopes crm:*:view.Oportunidades, facturas y cobros
La atribución lee el negocio que nació de cada campaña, hasta el cobro.Dominios y ruta de envío
Una campaña solo sale por un dominio verificado, y la ruta decide por dónde.
Marketing
Lo que lee de otros aplicativos y lo que les manda.
Envía a
- Quien pulsó un enlace pasa a lead u oportunidad.
Por herramientas: los segmentos y su previsualización están en marketing_lists; la conversión de quien pulsó, en marketing_campaigns; la atribución, en marketing_reports (campaign_attribution y entity_origin), y los dominios y la ruta, en email_sender_domains y email_sending_routes, las mismas herramientas que sirve el servidor del CRM. La conversión y la atribución exigen los aplicativos Marketing y CRM, porque el negocio vive en el CRM: una organización con Marketing y sin CRM las recibe denegadas.
Webhooks
Los eventos de Marketing (aperturas, clics, rebotes y bajas) alimentan las cifras del producto, pero hoy no se publican como webhooks hacia aplicaciones externas: el catálogo de eventos no tiene un área de Marketing.
Siguiente paso
Del clic al negocio: convierte a quienes pulsaron en leads u oportunidades del CRM con marketing_campaigns y sigue el resultado con campaign_attribution. Las guías de uso lo explican desde la aplicación: Definiciones de las métricas de Marketing, Medición del origen de tus campañas y Negocio por campaña. La API REST equivalente está en Marketing: API y herramientas MCP.