cli-anything-mailchimp

¿Qué hace cli-anything-mailchimp?

Identidad

Una CLI nativa para agentes de la API de Marketing de Mailchimp v3.0, construida sobre el framework CLI-Anything.

Qué Hace Esta CLI

• Gestionar audiencias (listas) — crear, actualizar, eliminar listas; agregar/actualizar/archivar miembros; gestionar campos de combinación, segmentos, etiquetas y webhooks.
• Ejecutar campañas — crear, programar, enviar, pausar, replicar y analizar campañas de correo electrónico.
• Leer informes — tasas de apertura, tasas de clics, estadísticas de rebotes, cancelaciones de suscripción, actividad de correo electrónico, datos geográficos.
• Controlar automatizaciones — crear y gestionar flujos de trabajo de correo electrónico automatizados.
• Gestionar comercio electrónico — tiendas, pedidos, clientes, productos, carritos y códigos promocionales.
• Usar plantillas, gestor de archivos, páginas de aterrizaje, campañas SMS, encuestas y todos los demás recursos de la API de Marketing.

Requisitos Previos

• Python 3.10+
• Variable de entorno MAILCHIMP_API_KEY configurada con tu clave de API (incluyendo el sufijo del centro de datos, ej. abc123-us8)

Instalación

# Desde el repositorio CLI-Anything (una vez fusionado):
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=mailchimp/agent-harness

# Durante el desarrollo:
cd mailchimp/agent-harness && pip install -e .

Referencia de Comandos

Raíz

Comando	Descripción
cli-anything-mailchimp ping	Verificación de salud — confirma la conectividad con la API
cli-anything-mailchimp root list	Obtener información de la cuenta
cli-anything-mailchimp --json <cmd>	Mostrar cualquier comando como JSON
cli-anything-mailchimp	Iniciar REPL interactivo

Listas (Audiencias)

Comando	Descripción
lists list	Listar todas las audiencias
lists get <LIST_ID>	Obtener información de la audiencia
lists create --data '<json>'	Crear audiencia
lists update <LIST_ID> --data '<json>'	Actualizar audiencia
lists delete <LIST_ID>	Eliminar audiencia
lists list-lists-id-members <LIST_ID>	Listar miembros
lists get-lists-id-members-id <LIST_ID> <SUBSCRIBER_HASH>	Obtener miembro por hash MD5
lists create-lists-id-members <LIST_ID> --data '<json>'	Agregar miembro
lists list-lists-id-merge-fields <LIST_ID>	Listar campos de combinación
lists create-lists-id-merge-fields <LIST_ID> --data '<json>'	Agregar campo de combinación
lists list-lists-id-segments <LIST_ID>	Listar segmentos
lists list-list-member-tags <LIST_ID> <SUBSCRIBER_HASH>	Listar etiquetas de miembro
lists create-list-member-tags <LIST_ID> <SUBSCRIBER_HASH> --data '<json>'	Agregar/eliminar etiquetas de miembro
lists list-lists-id-webhooks <LIST_ID>	Listar webhooks
lists create-lists-id-webhooks <LIST_ID> --data '<json>'	Agregar webhook

Campañas

Comando	Descripción
campaigns list	Listar campañas
campaigns get <CAMPAIGN_ID>	Obtener información de la campaña
campaigns create --data '<json>'	Crear campaña
campaigns update <CAMPAIGN_ID> --data '<json>'	Actualizar configuración de la campaña
campaigns delete <CAMPAIGN_ID>	Eliminar campaña
campaigns send <CAMPAIGN_ID>	Enviar campaña inmediatamente
campaigns schedule <CAMPAIGN_ID> --data '<json>'	Programar campaña
campaigns cancel-send <CAMPAIGN_ID>	Cancelar envío programado
campaigns pause <CAMPAIGN_ID>	Pausar campaña RSS
campaigns resume <CAMPAIGN_ID>	Reanudar campaña RSS
campaigns replicate <CAMPAIGN_ID>	Duplicar campaña
campaigns list-content <CAMPAIGN_ID>	Obtener contenido de la campaña
campaigns list-send-checklist <CAMPAIGN_ID>	Lista de verificación previa al envío

Informes

Comando	Descripción
reports list	Listar todos los informes de campañas
reports get <CAMPAIGN_ID>	Obtener informe resumido de la campaña
reports list-email-activity <CAMPAIGN_ID>	Actividad de apertura/clic por suscriptor
reports list-click-details <CAMPAIGN_ID>	Desglose de clics en enlaces
reports list-open-details <CAMPAIGN_ID>	Aperturas por suscriptor
reports list-unsubscribed <CAMPAIGN_ID>	Cancelaciones de suscripción
reports list-locations <CAMPAIGN_ID>	Desglose geográfico
reports list-domain-performance <CAMPAIGN_ID>	Estadísticas por dominio

Automatizaciones

Comando	Descripción
automations list	Listar automatizaciones
automations get <WORKFLOW_ID>	Obtener información de la automatización
automations create --data '<json>'	Crear automatización
automations pause <WORKFLOW_ID>	Pausar automatización
automations start <WORKFLOW_ID>	Iniciar automatización
automations archive <WORKFLOW_ID>	Archivar automatización
automations list-emails <WORKFLOW_ID>	Listar correos electrónicos de la automatización

Comercio Electrónico

Comando	Descripción
ecommerce list-ecommerce-stores	Listar tiendas
ecommerce get <STORE_ID>	Obtener información de la tienda
ecommerce create --data '<json>'	Agregar tienda
ecommerce list-ecommerce-stores-id-orders <STORE_ID>	Listar pedidos
ecommerce list-ecommerce-stores-id-products <STORE_ID>	Listar productos
ecommerce list-ecommerce-stores-id-customers <STORE_ID>	Listar clientes
ecommerce list-ecommerce-stores-id-carts <STORE_ID>	Listar carritos
ecommerce list-ecommerce-stores-id-promocodes <PROMO_RULE_ID> <STORE_ID>	Listar códigos promocionales

Otros Recursos

Grupo	Descripción
templates	Plantillas de correo electrónico (listar, obtener, crear, actualizar, eliminar)
template-folders	Carpetas de plantillas
campaign-folders	Carpetas de campañas
file-manager	Archivos y carpetas en el gestor de archivos
landing-pages	Páginas de aterrizaje (listar, crear, publicar, despublicar)
sms-campaigns	Campañas SMS (10 operaciones)
surveys	Encuestas (listar, obtener, publicar)
reporting	Informes de anuncios de Facebook y páginas de aterrizaje
search-campaigns	Buscar campañas por consulta
search-members	Buscar miembros en todas las audiencias
batches	Operaciones por lotes de la API
batch-webhooks	Webhooks de operaciones por lotes
verified-domains	Verificación de dominios de correo electrónico
authorized-apps	Aplicaciones conectadas por OAuth
connected-sites	Integraciones de sitios conectados
conversations	Conversaciones de la bandeja de entrada
activity-feed	Feed de actividad de la cuenta
account-exports	Exportaciones de datos de la cuenta

Salida JSON

Todos los comandos admiten --json a nivel raíz:

# Listar todas las audiencias como JSON
cli-anything-mailchimp --json lists list

# Obtener un informe de campaña como JSON
cli-anything-mailchimp --json reports get abc123def

# Canalizar a jq — usar el nombre de campo nativo de Mailchimp para el recurso
cli-anything-mailchimp --json lists list | jq '.lists[].name'
cli-anything-mailchimp --json campaigns list | jq '.campaigns[].id'

Formas de los objetos (respuesta nativa de la API de Mailchimp — usar la clave específica del recurso):

// Endpoints de lista — la clave coincide con el nombre del recurso (lists, campaigns, members, etc.)
{"lists": [...], "total_items": 42, "_links": [...]}
{"campaigns": [...], "total_items": 10, "_links": [...]}

// Recurso único GET / POST / PATCH
{"id": "abc123", "name": "Mi Lista", ...}

// DELETE
{"ok": true, "message": "Eliminado."}

// Error
{"ok": false, "message": "Recurso no encontrado: ...", "data": {...}}

Patrones Comunes para Agentes

# Obtener estado de la cuenta
cli-anything-mailchimp --json ping | jq '.health_status'

# Listar todos los IDs y nombres de audiencias
cli-anything-mailchimp --json lists list | jq '.lists[] | {id, name}'

# Encontrar todos los miembros suscritos en una audiencia
cli-anything-mailchimp --json lists list-lists-id-members <list_id> --status subscribed | jq '.members[].email_address'

# Crear una campaña y obtener su lista de verificación previa al envío
cli-anything-mailchimp --json campaigns create --data '{"type":"regular","settings":{"subject_line":"Hola","from_name":"Yo","reply_to":"[email protected]"}}' | jq '.id'
cli-anything-mailchimp --json campaigns list-send-checklist <campaign_id> | jq '.items[] | select(.result == false)'

# Obtener cancelaciones de suscripción de una campaña enviada
cli-anything-mailchimp --json reports list-unsubscribed <campaign_id> | jq '.unsubscribes[].email_address'

# Agregar un miembro a una audiencia (hash de suscriptor = MD5 del correo electrónico en minúsculas)
cli-anything-mailchimp --json lists create-members <list_id> --data '{"email_address":"[email protected]","status":"subscribed"}'

# Buscar un miembro en todas las audiencias
cli-anything-mailchimp --json search-members list --query "[email protected]" | jq '.exact_matches.members[]'

REPL Interactivo

Ejecuta cli-anything-mailchimp sin argumentos para entrar al REPL:

◆  cli-anything · Mailchimp
   v0.1.0
   Escribe help para comandos, quit para salir

◆ mailchimp ❯ ping
  ✓ {"health_status": "¡Todo está Chimpy!"}

◆ mailchimp ❯ --json lists list
{"lists": [...], "total_items": 3, "_links": [...]}

◆ mailchimp ❯ quit

Notas

• Hash de suscriptor: Mailchimp identifica a los miembros mediante el hash MD5 de su correo electrónico en minúsculas. Calcúlalo con python -c "import hashlib; email='[email protected]'; print(hashlib.md5(email.strip().lower().encode()).hexdigest())".
• Cuerpos de las solicitudes: Todos los comandos POST/PATCH/PUT aceptan --data '<json>'. Consulta la documentación de la API de Mailchimp para el esquema de cada endpoint.
• Centro de datos: Tu clave de API termina en -us8, -eu2, etc. La CLI lo extrae automáticamente — inclúyelo en MAILCHIMP_API_KEY.
• Límites de tasa: La API de Marketing limita la tasa a 10 conexiones concurrentes y un límite continuo por cuenta. Para operaciones masivas, usa el grupo batches.