Automatizar tu CRM con IA: guía de la API Contact Mailpro™ v3

La mayoría de los datos de CRM se ingresan dos veces — una en un formulario, otra en tu cabeza cuando olvidas actualizar el formulario. Los agentes de IA cierran ese hueco. Dale a Claude, GPT o Gemini una API de gestión de contactos y una descripción clara de la tarea, y sabrán crear o actualizar contactos, aplicar tags, construir segmentos y limpiar datos sin que un humano toque una interfaz. Esta guía muestra exactamente cómo hacerlo con la API Contact Mailpro™ v3.

En resumen

• CRM v3 es solo JSON (snake_case), autenticada con JWT Bearer Token.
• Obtén un token vía POST /v3/token — válido 365 días.
• Los contactos se identifican por UUIDs; listas, tags y campos por enteros.
• Cada endpoint está documentado en 20+ lenguajes en nuestro portal para desarrolladores.

¿Por qué exponer tu CRM a un agente de IA?

Los agentes como nueva capa de entrada

El ingreso de CRM por formulario es un problema resuelto — y mal resuelto desde hace 20 años. Los agentes te permiten saltarte el formulario. Un usuario escribe "nuevo lead: Alice de ShopCorp, interesada en nuestro plan enterprise, volver a llamar la próxima semana\". El agente parsea, llama POST /v3/Contact con datos estructurados, la etiqueta "interés-enterprise" y agenda un seguimiento. Cero pulsaciones en un formulario.

Tres escenarios concretos

• Enriquecimiento de leads. Un webhook dispara desde un formulario; el agente enriquece con fuentes públicas, upsertea el contacto en Mailpro™ v3, y lo etiqueta con un lead score.
• Higiene de listas. Cron semanal; el agente revisa duplicados, datos obsoletos, contactos sin clasificar, y reorganiza los tags.
• Segmentación dinámica. "Mueve a todos los que abrieron la campaña de rebajas al segmento warm-leads" — el agente lee las estadísticas de v2 y llama v3 para reetiquetar.

Autenticar un agente de IA con JWT

POST /v3/token con grant password

La vía más simple:

curl -X POST "https://api.mailpro.com/v3/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "[email protected]" \
  -d "password=YOUR_API_KEY"

Respuesta:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 31535999,
  "refresh_token": "eyJhbGciOi..."
}

Guarda el access_token de forma segura (variable de entorno del servidor, bóveda) y envíalo como Authorization: Bearer <token> en cada llamada v3 subsecuente.

Vida útil del token: 365 días

Los tokens Mailpro™ son longevos por diseño — los agentes de IA corren de forma continua, no quieres tormentas de refresh. Si necesitas rotación, usa el flujo de refresh token o emite un nuevo token periódicamente.

Grants de terceros

Si construyes una integración Zapier, Make o Microsoft Flow, usa los grants dedicados (zapier, microsoft-flow, etc.). Emiten un JWT con rol ThirdParty. La mayoría de las integraciones de agentes funciona con el grant password.

Paso a paso: "Claude, añade este contacto, etiqueta VIP, ponlo en la lista 42"

Aquí brilla el diseño de v3: un prompt, tres llamadas API, cero interfaz.

1. Esquemas de herramientas

Dale al agente tres herramientas estrechas — no una grande. Las estrechas las elige mejor el modelo.

tools = [
    {
        "name": "upsert_contact",
        "description": "Crea o actualiza un contacto Mailpro por email.",
        "input_schema": {
            "type": "object",
            "properties": {
                "email":      {"type": "string", "format": "email"},
                "first_name": {"type": "string"},
                "last_name":  {"type": "string"},
                "fields":     {"type": "object", "description": "Valores de campos personalizados"}
            },
            "required": ["email"]
        }
    },
    {
        "name": "tag_contact",
        "description": "Aplica una tag a un contacto por UUID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "contact_id": {"type": "string"},
                "tag_name":   {"type": "string"}
            },
            "required": ["contact_id", "tag_name"]
        }
    },
    {
        "name": "add_to_list",
        "description": "Agrega un contacto a una lista Mailpro por ID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "contact_id": {"type": "string"},
                "list_id":    {"type": "integer"}
            },
            "required": ["contact_id", "list_id"]
        }
    }
]

2. El razonamiento del agente

Ante el prompt "Agrega a Alice Zhang de ShopCorp ([email protected]), etiqueta VIP, ponla en la lista 42", Claude razona:

1. Llamar upsert_contact con {email: "[email protected]", first_name: "Alice", last_name: "Zhang"}.
2. Leer el contact_id devuelto.
3. Llamar tag_contact con {contact_id, tag_name: "VIP"}.
4. Llamar add_to_list con {contact_id, list_id: 42}.

Tres llamadas a herramienta, una intención del usuario. Eso es el bucle del agente.

3. Ejecutar en secuencia

def execute_tool(name, args, token):
    base = "https://api.mailpro.com/v3"
    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

    if name == "upsert_contact":
        r = requests.post(f"{base}/Contact", headers=headers, json={
            "email": args["email"],
            "first_name": args.get("first_name"),
            "last_name": args.get("last_name"),
            "fields": args.get("fields", {})
        })
        return r.json()

    elif name == "tag_contact":
        r = requests.post(f"{base}/Tag/{args['tag_name']}/Contact",
                          headers=headers, json={"contact_id": args["contact_id"]})
        return r.json()

    elif name == "add_to_list":
        r = requests.post(f"{base}/List/{args['list_id']}/Contact",
                          headers=headers, json={"contact_id": args["contact_id"]})
        return r.json()

4. Gestionar reglas de negocio (respuestas 406)

v3 devuelve HTTP 406 para violaciones de reglas de negocio, con un body JSON:

{ "Message": "A contact already exist with the same Email" }

Motivos 406 comunes:

• Email cannot be empty
• Email has an invalid format
• A contact already exist with the same Email
• The email address was unsubscribed permanently
• One or more lists have reached the contact limit

Enseña al agente a leer el campo Message y a recuperarse con elegancia: en duplicado, buscar el contacto existente y actualizarlo en vez de rendirse. En email inválido, pedir al usuario una corrección.

¿Cansado del mantenimiento manual de listas? Los planes de Mailpro incluyen la API de Contactos para que tu agente de IA mantenga las listas limpias y segmentadas — automáticamente.

Campos personalizados y segmentos

Crear un campo personalizado (/v3/Field)

curl -X POST "https://api.mailpro.com/v3/Field" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "lead_score", "field_type": "Number"}'

Construir un segmento con reglas (/v3/Segment)

Los segmentos son dinámicos — se actualizan cuando cambian los datos de los contactos. A los agentes les encantan: creas un segmento una vez, las reglas capturan contactos para siempre.

"Claude, mueve a los que abrieron la última campaña al segmento Hot Leads"

Justo la clase de tarea multietapa en la que v3 brilla. El agente:

1. Consulta las stats v2 (/stats/open) para encontrar a los que abrieron la última campaña.
2. Para cada uno, llama v3 para añadirlo al segmento Hot Leads (vía tag o actualizando un campo de score).

Los flujos cross-API como este son exactamente lo que desbloquean los agentes de IA unificados.

Importar contactos a escala vía agente

Cuando el agente reacciona a un evento "nueva lista de leads" (upload CSV, hoja compartida, exportación CRM), no hagas bucle uno-a-uno. Usa el endpoint de import en bloque:

curl -X POST "https://api.mailpro.com/v3/Import/Upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "id_list=42" \
  -F "[email protected]" \
  -F "webhook_url=https://example.com/hooks/import-done"

El endpoint devuelve un import_job_id de inmediato. Al terminar el procesamiento, Mailpro™ hace POST de un callback a tu webhook_url con los conteos (importados / omitidos / inválidos). Tu agente puede usar el webhook como señal para correr acciones siguientes ("import listo → lanzar campaña de bienvenida").

El flujo completo del agente: enriquecimiento comercial

Trigger: webhook de nuevo cliente Stripe. Objetivo: el agente debe enriquecer, añadir al CRM y enviar un email de bienvenida.

1. Enriquecer. El agente llama a una API de enriquecimiento externa (Clearbit, People Data Labs, scraper propio) para obtener nombre de empresa, cargo, LinkedIn.
2. Upsert en Mailpro™ v3. POST /v3/Contact con email + campos enriquecidos.
3. Tag y lista. El agente etiqueta stripe-customer y añade a la lista Clientes Pagos.
4. Email de bienvenida. El agente llama a la API v2 /send/sendmail.json con bienvenida personalizada.

Cuatro llamadas, dos APIs, un onboarding sin costuras. Costo humano: cero.

Consejos y trampas

snake_case vs PascalCase

v3 es snake_case (first_name, list_id, contact_id). v2 es PascalCase (FirstName, ListId). Si el agente habla con ambas, dilo explícitamente en el prompt del sistema para que no invente nombres de campo.

Los errores de negocio devuelven 406, no 400

400 = datos malformados. 406 = datos válidos pero violando una regla de negocio. El agente debe distinguir — 400 es bug de código; 406 es un resultado normal del que debe recuperarse.

50 000 solicitudes mensuales por defecto

v3 tiene un tope mensual por cuenta. Los agentes en bucle agresivo lo tocan. Agrupa con /v3/Contact/Multiple cuando sea posible. El tope está en tu panel de cuenta.

Caso de estudio (ficticio): "CoraSegura" — corredor IA que triage 2.000 leads al día

CoraSegura es un agregador de corredores de seguros. Cada día, 2.000 leads llegan al webhook desde comparadores. Antes, dos operadores limpiaban y enrutaban cada lead a mano. Con Claude conectado a Mailpro™ v3, el flujo quedó así:

1. Webhook dispara → Claude recibe el JSON del lead.
2. Claude enriquece (valida email, normaliza teléfono a E.164, deduce producto de seguros dede>Clientes Pagos.
3. Email de bienvenida. El agente llama a la API v2 /send/sendmail.json con bienvenida personalizada.

Cuatro llamadas, dos APIs, un onboarding sin costuras. Costo humano: cero.

Consejos y trampas

snake_case vs PascalCase

v3 es snake_case (first_name, list_id, contact_id). v2 es PascalCase (FirstName, ListId). Si el agente habla con ambas, dilo explícitamente en el prompt del sistema para que no invente nombres de campo.

Los errores de negocio devuelven 406, no 400

400 = datos malformados. 406 = datos válidos pero violando una regla de negocio. El agente debe distinguir — 400 es bug de código; 406 es un resultado normal del que debe recuperarse.

50 000 solicitudes mensuales por defecto

v3 tiene un tope mensual por cuenta. Los agentes en bucle agresivo lo tocan. Agrupa con /v3/Contact/Multiple cuando sea posible. El tope está en tu panel de cuenta.

Caso de estudio (ficticio): "CoraSegura" — corredor IA que triage 2.000 leads al día

CoraSegura es un agregador de corredores de seguros. Cada día, 2.000 leads llegan al webhook desde comparadores. Antes, dos operadores limpiaban y enrutaban cada lead a mano. Con Claude conectado a Mailpro™ v3, el flujo quedó así:

1. Webhook dispara → Claude recibe el JSON del lead.
2. Claude enriquece (valida email, normaliza teléfono a E.164, deduce producto de seguros deisma base de contactos. Un contacto creado vía v2 es visible y gestionable vía v3, y viceversa.

    

   ¿Cómo funcionan los campos personalizados con IA?

   Crea el campo una vez vía POST /v3/Field con un tipo (Text, Number, Date, Boolean). A partir de ahí, el agente puede fijar valores sobre contactos mediante fields en el payload. Los campos personalizados también sirven como variables de personalización en campañas.

   ¿Qué diferencia hay entre lista, tag y segmento?

   Una lista es una colección estática a la que añades contactos explícitamente. Una tag es una etiqueta ligera (un contacto puede tener muchas). Un segmento es una consulta dinámica — "todos los contactos con tag='VIP' y country='ES'" — que se actualiza sola al cambiar los datos. Ver también nuestra guía de entregabilidad para cómo una buena segmentación mejora la entrega.