Invia Email e SMS con un Agente AI tramite l'API Mailpro™

Un agente AI che sa solo conversare è un chatbot. Un agente AI capace di inviare l'email, mandare un SMS al cliente e aggiornare la scheda del contatto è un collega di squadra. Questa guida spiega come collegare Claude, GPT o qualsiasi LLM che supporti il tool calling alle API di Mailpro™, così che il tuo agente possa inviare email e SMS in autonomia, in sicurezza, con ogni messaggio registrato e tracciabile.

In breve

• Mailpro™ mette a disposizione tre API HTTPS che il tuo agente può chiamare: la Email API v2 (email transazionali e campagne), la CRM API v3 (contatti, liste, tag) e la SMS API.
• Ogni azione viene racchiusa in un piccolo strumento (tool): il modello decide quando chiamarlo, il tuo codice esegue la richiesta HTTP.
• Autenticati con un token OAuth 2.0 limitato agli scope di cui l'agente ha bisogno, mai con la tua chiave API principale inserita in un prompt.
• Usa i webhook (email.delivered, email.bounced, sms.delivered…) perché l'agente sappia cosa è successo davvero.
• Mantieni un passaggio di approvazione umana per gli invii massivi e per i destinatari sconosciuti.

Perché dare al tuo agente AI il potere di inviare email e SMS?

Perché gran parte del valore di un agente sta in ciò che fa dopo aver capito la richiesta. Un agente di assistenza che scrive una bozza di risposta è utile; uno che invia la risposta, conferma il rimborso via SMS e tagga il contatto come "rimborsato" chiude il ticket. Attività tipiche che oggi funzionano già bene:

• Follow-up di ordini e prenotazioni — un'email di conferma con una nota personale scritta dall'agente, più un SMS di promemoria il giorno prima.
• Smistamento dell'assistenza — l'agente classifica il ticket, risponde via email alle richieste semplici e inoltra le altre a una persona.
• Codici monouso e avvisi — l'agente genera un codice, lo invia via SMS e lo verifica quando l'utente risponde.
• Riepiloghi giornalieri — l'agente legge i dati della giornata e invia un'unica email di sintesi invece di quaranta notifiche.

Cosa sono le API di Mailpro™, in 30 secondi?

Tutte e tre accettano lo stesso token OAuth 2.0 (rilasciato una sola volta su https://api.mailpro.com/oauth/token), restituiscono JSON e condividono una quota mensile di richieste per account. Ogni endpoint è documentato, con esempi di richiesta e risposta, sul portale sviluppatori di Mailpro™.

Come fa un agente AI a chiamare un'API email o SMS?

Tramite il tool calling (Anthropic lo chiama tool use, OpenAI function calling). Descrivi ogni azione come uno strumento con uno schema JSON. Quando il modello decide che serve un'azione, restituisce una chiamata allo strumento con i relativi argomenti; il tuo codice li convalida, chiama l'API di Mailpro™ e restituisce il risultato al modello. Il modello non possiede mai le tue credenziali e non esegue mai direttamente la richiesta HTTP.

Se preferisci non scrivere il ciclo da solo, gli stessi strumenti possono essere esposti tramite un server MCP (Model Context Protocol), che Claude Desktop, Claude Code e Cursor possono usare direttamente. Le chiamate API sottostanti sono le stesse.

Esempio minimo: Claude invia un'email e un SMS

1. Ottieni un token con scope limitati

curl -X POST https://api.mailpro.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=email:send email:read sms:send"

Crea il client ID e il secret nel tuo account Mailpro™, in Settings → API access (Impostazioni → accesso API). Il token di accesso dura 20 minuti; il tuo codice ne richiede uno nuovo quando scade.

2. Definisci gli strumenti

tools = [
  {
    "name": "send_email",
    "description": "Invia un'email transazionale a un singolo destinatario.",
    "input_schema": {
      "type": "object",
      "properties": {
        "to": {"type": "string"},
        "subject": {"type": "string"},
        "html": {"type": "string"}
      },
      "required": ["to", "subject", "html"]
    }
  },
  {
    "name": "send_sms",
    "description": "Invia un SMS (max 160 caratteri) a un singolo numero di telefono.",
    "input_schema": {
      "type": "object",
      "properties": {
        "to": {"type": "string", "description": "Formato internazionale, ad es. +41791234567"},
        "message": {"type": "string"}
      },
      "required": ["to", "message"]
    }
  }
]

3. Esegui le chiamate agli strumenti

import requests

API = "https://api.mailpro.com"
SENDER_ID = 201  # ottenuto da GET /v2/senderEmail/list

def run_tool(name, args, token):
    h = {"Authorization": f"Bearer {token}"}
    if name == "send_email":
        r = requests.post(f"{API}/v2/send/sendmail.json", headers=h, data={
            "IDEmailExp": SENDER_ID,
            "EmailData": args["to"],
            "Subject": args["subject"],
            "BodyHTML": args["html"],
            "ActivateStatistics": "true",
        })
    elif name == "send_sms":
        r = requests.post(f"{API}/sms/send/add_single.json", headers=h, data={
            "to": args["to"],
            "message": args["message"],
        })
    else:
        return {"error": "unknown tool"}
    return r.json()

Collega run_tool al tuo consueto ciclo Claude (o OpenAI): invia il messaggio dell'utente con tools, esegui ogni chiamata allo strumento restituita dal modello e rimanda il risultato come tool result. La chiamata email restituisce un IdSingleSend; quella SMS un Id. Conservali entrambi: servono a tracciare la consegna.

Preferisci non scrivere codice? Le email automatiche di Mailpro inviano conferme, promemoria e avvisi in base a trigger che configuri in pochi clic.

Come fa l'agente a sapere se il messaggio è stato consegnato?

Una risposta 200 significa che Mailpro™ ha accettato il messaggio, non che sia arrivato nella casella di posta o sul telefono. Ci sono due modi per chiudere il cerchio:

• Polling — GET /v2/send/{IdSingleSend}/status.json restituisce queued, sent, delivered, deferred o bounced per un'email transazionale.
• Webhook (consigliato) — ti iscrivi una sola volta con POST /webhooks e Mailpro™ invia un evento firmato al tuo server: email.delivered, email.bounced, email.opened, sms.delivered, sms.failed e altri. Ogni richiesta contiene un header HMAC X-Mailpro-Signature che ti permette di verificare che provenga da Mailpro™.

Rimanda questi eventi all'agente e potrà reagire da solo: ritentare via email un SMS non riuscito, oppure segnalare a una persona un indirizzo in bounce.

Sicurezza e buone pratiche per gli invii gestiti dall'AI

Dai all'agente un token con scope limitati, non le tue chiavi

I token OAuth contengono scope come email:send, email:read, contacts:read o sms:send. Un agente che invia solo conferme non ha bisogno di contacts:write. Una chiamata al di fuori dei suoi scope fallisce con 403 insufficient_scope. Conserva il client secret in variabili d'ambiente lato server; non inserirlo mai in un prompt.

Mantieni una persona nel ciclo per gli invii a rischio

Lascia che l'agente invii da solo i messaggi individuali, ma richiedi un'approvazione per le campagne (/v2/send/campaign, /sms/send/add), per i destinatari che non sono nelle tue liste di contatti e per qualsiasi messaggio che parli di denaro. Una semplice allowlist di domini o liste di destinatari nel codice dei tuoi strumenti impedisce che un prompt sbagliato finisca per inviare un mailing massivo ai tuoi clienti.

Rispetta la quota e attendi prima di ritentare in caso di errore

Le tue richieste API condividono una quota mensile tra le API Email, CRM e SMS (verificala con GET /v2/account/limits.json). Un agente bloccato in un ciclo può esaurirla in fretta: limita il numero di chiamate agli strumenti per conversazione e, sulle risposte 429 e 5xx, ritenta con un backoff esponenziale invece di riprovare subito.

Rispetta il consenso e le disiscrizioni

I contatti disiscritti e in blacklist vengono saltati automaticamente, e l'API te lo segnala. Non lasciare che l'agente aggiri questa regola. Per gli SMS, verifica le norme di ogni paese di destinazione prima di inviare messaggi di marketing.

Registra tutto

Salva ogni chiamata agli strumenti con i relativi argomenti, la risposta dell'API e l'ID restituito. Quando un cliente chiede "perché ho ricevuto questo messaggio?", puoi rispondere in pochi secondi.

Caso di studio (fittizio): "LoopKart" affida a Claude le email post-acquisto

LoopKart è un piccolo negozio online che vende attrezzature da cucina ricondizionate. Le sue email post-acquisto erano un unico modello uguale per tutti. Il team ha collegato Claude alla Email API di Mailpro™ con un solo strumento send_email: dopo ogni ordine, l'agente legge l'ordine e lo storico del cliente, scrive un breve paragrafo personalizzato (consigli di manutenzione per il prodotto specifico, un pensiero se si tratta di un cliente abituale) e invia l'email tramite /v2/send/sendmail. Un secondo strumento invia un SMS alla spedizione del pacco. Gli ordini sopra un importo prestabilito, e qualsiasi messaggio che menzioni un rimborso, attendono il clic di una persona prima dell'invio. La configurazione ha richiesto al team due giorni, in gran parte dedicati a scrivere e testare la regola di approvazione.

Domande frequenti

Quali modelli di AI funzionano con l'API di Mailpro™?

Qualsiasi modello che supporti il tool calling o il function calling: Claude, GPT, Gemini, Mistral e i modelli open source serviti con un framework di tool calling. L'API in sé è semplice HTTPS con JSON, quindi al modello basta un sottile livello di integrazione.

Serve un piano Mailpro™ a pagamento per iniziare?

No. Puoi iniziare con il piano gratuito, testare tutto e passare a un piano superiore quando i tuoi volumi lo giustificano. Consulta i prezzi di Mailpro.

L'agente può inviare a un'intera lista?

Sì, con /v2/send/campaign per le email e /sms/send/add per gli SMS. Per questi invii consigliamo un passaggio di approvazione umana.

Esiste un server MCP?

Puoi esporre gli stessi strumenti tramite qualsiasi framework per server MCP; le chiamate sottostanti sono quelle mostrate sopra.

Per approfondire

• Email transazionali e campagne nel dettaglio: API per email transazionali per agenti AI
• Contatti, liste e tag: Automatizza il tuo CRM con l'AI
• SMS, codici e promemoria: Inviare SMS con un agente AI
• Arrivare nella casella di posta: la deliverability dell'email
• Il gateway SMS vero e proprio: API SMS di Mailpro