Automatizzare il CRM con AI: guida all'API Contatti Mailpro™ v3

La maggior parte dei dati CRM viene inserita due volte: una in un form, una nella tua testa quando dimentichi di aggiornare il form. Gli agenti AI colmano questo vuoto. Dai a Claude, GPT o Gemini un'API di gestione contatti e una descrizione chiara del compito, e sapranno creare o aggiornare contatti, applicare tag, costruire segmenti, pulire dati senza che un umano tocchi un'interfaccia. Questa guida mostra esattamente come farlo con l'API Contatti Mailpro™ v3.

In breve

• CRM v3 è full JSON (snake_case), autenticata con JWT Bearer Token.
• Ottieni un token via POST /v3/token — valido 365 giorni.
• I contatti sono identificati da UUID; liste, tag e campi da interi.
• Ogni endpoint è documentato in 20+ linguaggi sul nostro portale sviluppatori.

Perché esporre il CRM a un agente AI?

Gli agenti come nuova interfaccia di inserimento

L'inserimento CRM via form è un problema risolto — e risolto male da 20 anni. Gli agenti permettono di saltare il form. Un utente scrive "nuovo lead: Alice di ShopCorp, interessata al nostro piano enterprise, richiamare la prossima settimana". L'agente parsa, chiama POST /v3/Contact con dati strutturati, la tagga "enterprise-interesse" e programma un follow-up. Zero digitazioni in un form.

Tre scenari concreti

• Arricchimento lead. Webhook da form; l'agente arricchisce con fonti pubbliche, upsertta il contatto in Mailpro™ v3, e lo tagga con un lead score.
• Igiene liste. Cron settimanale; l'agente controlla duplicati, dati obsoleti, contatti non classificati, e riorganizza i tag di conseguenza.
• Segmentazione dinamica. "Sposta tutti quelli che hanno aperto la campagna Saldi nel segmento warm-leads" — l'agente legge le statistiche da v2 e chiama v3 per ri-taggare.

Autenticare un agente AI con JWT

POST /v3/token con grant password

La via più semplice:

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"

Risposta:

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

Custodisci l'access_token in modo sicuro (variabile d'ambiente server, vault) e passalo come Authorization: Bearer <token> su ogni chiamata v3 successiva.

Durata del token: 365 giorni

I token Mailpro™ sono pensati per durare — gli agenti AI girano in continuo, non vuoi tempeste di refresh. Se ti serve rotazione, usa il flow refresh token o emetti un nuovo token periodicamente.

Grant di terze parti

Se costruisci un'integrazione Zapier, Make o Microsoft Flow, usa i grant dedicati (zapier, microsoft-flow ecc.). Emettono un JWT con ruolo ThirdParty. Per la maggior parte delle integrazioni di agenti, il grant password basta.

Passo dopo passo: "Claude, aggiungi questo contatto, tagga VIP, mettilo nella lista 42"

Qui il design di v3 brilla: un prompt, tre chiamate API, zero interfaccia.

1. Schemi degli strumenti

Dai all'agente tre strumenti stretti, non uno grande. Gli strumenti stretti sono scelti più affidabilmente dal modello.

tools = [
    {
        "name": "upsert_contact",
        "description": "Crea o aggiorna un contatto Mailpro dall'email.",
        "input_schema": {
            "type": "object",
            "properties": {
                "email":      {"type": "string", "format": "email"},
                "first_name": {"type": "string"},
                "last_name":  {"type": "string"},
                "fields":     {"type": "object", "description": "Valori dei campi personalizzati"}
            },
            "required": ["email"]
        }
    },
    {
        "name": "tag_contact",
        "description": "Applica un tag a un contatto per UUID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "contact_id": {"type": "string"},
                "tag_name":   {"type": "string"}
            },
            "required": ["contact_id", "tag_name"]
        }
    },
    {
        "name": "add_to_list",
        "description": "Aggiunge un contatto a una lista Mailpro per ID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "contact_id": {"type": "string"},
                "list_id":    {"type": "integer"}
            },
            "required": ["contact_id", "list_id"]
        }
    }
]

2. Il ragionamento dell'agente

Al prompt "Aggiungi Alice Zhang di ShopCorp ([email protected]), tagga VIP, mettila nella lista 42", Claude ragiona:

1. Chiama upsert_contact con {email: "[email protected]", first_name: "Alice", last_name: "Zhang"}.
2. Legge il contact_id restituito.
3. Chiama tag_contact con {contact_id, tag_name: "VIP"}.
4. Chiama add_to_list con {contact_id, list_id: 42}.

Tre chiamate a strumento, un'intenzione dell'utente. È il ciclo dell'agente.

3. Eseguire in sequenza

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. Gestire le regole di business (risposte 406)

v3 restituisce HTTP 406 per violazioni delle regole di business, con un body JSON:

Stanco della manutenzione manuale delle liste? I piani di Mailpro includono l’API Contatti così il tuo agente IA mantiene le liste pulite e segmentate — in automatico.

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

Motivi 406 comuni:

• 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

Insegna all'agente a leggere il campo Message e a recuperare con eleganza: su duplicato, cerca il contatto esistente e aggiornalo invece di mollare. Su email non valida, chiedi una correzione all'utente.

Campi personalizzati e segmenti

Creare un campo personalizzato (/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"}'

Costruire un segmento con regole (/v3/Segment)

I segmenti sono dinamici — si aggiornano quando cambiano i dati dei contatti. Gli agenti li adorano: crei un segmento una volta, le regole catturano i contatti per sempre.

"Claude, sposta chi ha aperto l'ultima campagna nel segmento Hot Leads"

Esattamente il tipo di compito multi-step in cui v3 brilla. L'agente:

1. Interroga le statistiche v2 (/stats/open) per trovare chi ha aperto l'ultima campagna.
2. Per ogni apertura, chiama v3 per aggiungere al segmento Hot Leads (via tag o aggiornando un campo di scoring).

I workflow cross-API come questo sono esattamente ciò che gli agenti AI unificati sbloccano.

Importare contatti su larga scala via agente

Quando l'agente reagisce a un evento "nuova lista di lead" (upload CSV, foglio condiviso, export CRM), non ciclare uno-per-uno. Usa l'endpoint import bulk:

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"

L'endpoint restituisce subito un import_job_id. Quando l'elaborazione termina, Mailpro™ fa POST di un callback al tuo webhook_url con i conteggi (importati / scartati / non validi). L'agente può usare il webhook come segnale per azioni successive ("import fatto → lancio campagna di benvenuto").

Il flow completo dell'agente: arricchimento commerciale

Trigger: webhook di nuovo cliente Stripe. Obiettivo: l'agente deve arricchire, aggiungere al CRM e inviare un'email di benvenuto.

1. Arricchire. L'agente chiama un'API esterna (Clearbit, People Data Labs, scraper custom) per nome azienda, ruolo, LinkedIn.
2. Upsert in Mailpro™ v3. POST /v3/Contact con email + campi arricchiti.
3. Tag e lista. L'agente tagga stripe-customer e aggiunge alla lista Clienti Paganti.
4. Email di benvenuto. L'agente chiama l'API v2 /send/sendmail.json con un benvenuto personalizzato.

Quattro chiamate a strumento, due API, un onboarding fluido. Costo umano: zero.

Consigli e insidie

snake_case vs PascalCase

v3 è snake_case (first_name, list_id, contact_id). v2 è PascalCase (FirstName, ListId). Se l'agente parla a entrambe, indicalo esplicitamente nel system prompt per evitare che inventi nomi di campo.

Gli errori di business rispondono 406, non 400

400 = dati malformati. 406 = dati validi ma in violazione di una regola di business. L'agente deve distinguere — 400 è un bug di codice; 406 è un esito normale da cui recuperare.

50 000 richieste mensili di default

v3 ha un tetto mensile per account. Gli agenti in loop aggressivo lo toccano. Raggruppa con /v3/Contact/Multiple quando possibile. Il tetto è nella tua dashboard account.

Caso studio (fittizio): "CoraAssicura" — broker AI che tria 2.000 lead al giorno

CoraAssicura è un aggregatore di broker assicurativi. Ogni giorno 2.000 lead atterrano nel webhook dai comparatori. Prima, due operatori pulivano e instradavano manualmente ogni lead. Con Claude collegato a Mailpro™ v3, il workflow è diventato:

1. Webhook → Claude riceve il JSON del lead.
2. Claude arricchisce (valida email, normalizza telefono in E.164, deduce prodotto assicurativo dal testo libero).
3. Claude chiama upsert_contact, applica i tag (auto, casa, vita), aggiunge alla lista giusta.
4. Claude punteggia il lead (0–100) e scrive lo score nel campo lead_score.
5. I lead con alto score innescano un email di benvenuto v2.

Il tempo di elaborazione per lead è sceso da 6 minuti (umano) a 4 secondi (agente). La qualità dei dati è migliorata — Claude è più severo sulla validazione email di umani stanchi. I due operatori sono stati riassegnati al vero lavoro di intermediazione.

Prossimo passo

Con v3 che gestisce il CRM e v2 per l'invio, resta l'SMS. Vai alla nostra guida API SMS per dare all'agente l'ultimo canale. O torna alla guida pilastro.

Documentazione di riferimento: API CRM v3. Prezzi: prezzi Mailpro.

FAQ

Mailpro v3 supporta OAuth o solo grant password?

Entrambi. password è il più semplice; client_credentials per flussi macchina-a-macchina; zapier, automateio e microsoft-flow sono grant dedicati a terze parti che emettono un JWT con ruolo ThirdParty.

Posso migrare contatti Mailpro v2 a v3?

Sì — le due API toccano lo stesso database contatti. Un contatto creato via v2 è visibile e pilotabile via v3, e viceversa.

Come funzionano i campi personalizzati con l'AI?

Crea il campo una volta via POST /v3/Field con un tipo (Text, Number, Date, Boolean). Da lì, l'agente può impostare valori sui contatti tramite fields nel payload. I campi personalizzati servono anche come variabili di personalizzazione nelle campagne email.

Che differenza c'è tra lista, tag e segmento?

Una lista è una collezione statica in cui aggiungi esplicitamente contatti. Un tag è un'etichetta leggera (un contatto può averne diversi). Un segmento è una query dinamica — "tutti i contatti con tag='VIP' e country='IT'" — che si aggiorna da sola al variare dei dati. Vedi anche la nostra guida sulla deliverability email per capire come una buona segmentazione migliora la consegna.