API di email transazionali per agenti AI: guida Mailpro™ v2

Se hai letto la nostra guida agli agenti AI e alle API di Mailpro™, conosci lo schema: il modello decide, il tuo codice invia. Questo articolo approfondisce una sola API, la Email API v2 di Mailpro™, e illustra una configurazione funzionante per le email transazionali e le campagne gestite da Claude, GPT o qualsiasi LLM che supporti il tool calling, con gli endpoint e i parametri esatti.

In breve

• URL di base https://api.mailpro.com/v2, risposte in JSON, token bearer OAuth 2.0 (oppure la vecchia coppia IdClient + ApiKey).
• Un'email a una persona: POST /send/sendmail.json. Un modello salvato a un'intera lista: POST /send/campaign.json.
• Monitora ogni email transazionale con GET /send/{IdSingleSend}/status.json o con i webhook email.delivered / email.bounced.
• Importa contatti in blocco da un agente con POST /import/upload.json (CSV o XLSX, fino a 50 MB).

Email gestite dall'AI: quali casi d'uso valgono davvero la pena?

Conferme d'ordine intelligenti

Una conferma standard è un modello. Un agente può aggiungere una nota personale ("Grazie per aver scelto la Blue XL, la preferita dei nostri clienti") e consigli pertinenti, poi inviarla tramite l'API. Mantieni l'affidabilità di un modello strutturato con il calore di un messaggio scritto a mano.

Smistamento automatico del supporto

Quando arriva un ticket, l'agente lo classifica, prepara una risposta e, se è abbastanza sicuro e l'argomento rientra in un elenco approvato, la invia. Tutto il resto passa a una persona, con la bozza allegata.

Riepiloghi invece di valanghe di email

L'agente legge gli eventi della giornata (fatture, iscrizioni, avvisi) e invia un unico riepilogo alle 18:00: "Oggi: 12 pagate, 3 scadute, 2 da verificare." Una sola email, niente rumore. L'API si occupa della consegna; il modello, della sintesi.

Come si configura la Email API v2 in 5 minuti?

1. Ottieni le credenziali

Nel tuo account Mailpro™, vai su Settings → API access. Per un agente, crea un client OAuth e richiedi solo gli scope di cui ha bisogno, di solito email:send e email:read. Anche le vecchie credenziali IdClient (numerico) e ApiKey (GUID) funzionano, ma non sono limitate dagli scope: riservale ai tuoi script di back-end.

2. Verifica la connessione

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.mailpro.com/v2/account/credits.json

Dovresti ricevere i crediti email rimanenti in formato JSON. Un 401 indica che il token o la chiave sono errati; un 403 insufficient_scope indica che al token manca account:read.

3. Trova l'ID del mittente

Le email partono da un indirizzo mittente convalidato. GET /senderEmail/list.json restituisce questi indirizzi con i relativi ID; è questo l'ID che passerai come IDEmailExp.

Passo dopo passo: fai inviare a Claude un'email transazionale

L'esempio usa Claude di Anthropic, ma lo stesso schema funziona con il function calling di OpenAI o il tool use di Gemini: cambia l'SDK, non l'architettura.

1. Definisci lo strumento

tools = [{
  "name": "send_transactional_email",
  "description": "Invia un'email a un cliente tramite Mailpro.",
  "input_schema": {
    "type": "object",
    "properties": {
      "to":      {"type": "string"},
      "subject": {"type": "string"},
      "html":    {"type": "string", "description": "Corpo HTML completo"}
    },
    "required": ["to", "subject", "html"]
  }
}]

2. Scrivi il prompt di sistema

Aiuti gli operatori del customer success a scrivere e inviare email di follow-up.
Chiama send_transactional_email solo dopo la conferma della persona.
Sii conciso e cordiale, e includi sempre un link con una call to action chiara.

3. Esegui la chiamata a /send/sendmail

import requests

def send_transactional_email(args, token, sender_id):
    r = requests.post(
        "https://api.mailpro.com/v2/send/sendmail.json",
        headers={"Authorization": f"Bearer {token}"},
        data={
            "IDEmailExp": sender_id,       # da /senderEmail/list
            "EmailData":  args["to"],      # email,campo1,campo2...
            "Subject":    args["subject"],
            "BodyHTML":   args["html"],
            "ActivateStatistics": "true",  # tracciamento di aperture e clic
        },
    )
    r.raise_for_status()
    return r.json()   # {"SingleSend": {"IdSingleSend": 8001, ...}}

Campi facoltativi utili: DatePlanned (ISO 8601) per programmare l'invio invece di inviare subito, ReplyTo, BodyText per una versione in solo testo e attachments. Restituisci il JSON al modello come risultato dello strumento, così potrà comunicare all'utente che l'email è in arrivo.

Stai collegando gli invii transazionali? Le email automatiche di Mailpro partono all'istante a ogni evento — ricevute, conferme, avvisi — con una consegna su cui puoi contare.

4. Conferma la consegna

GET /send/8001/status.json restituisce delivered, bounced (con BounceType e il DiagCode del server), deferred, sent, scheduled o queued. Aspettati delivered circa cinque minuti dopo la consegna al server. Per un riscontro in tempo reale, iscriviti ai webhook email.delivered e email.bounced invece di interrogare lo stato a ripetizione.

Campagne: l'agente prepara, una persona preme invia

Per un invio a un'intera lista, l'agente lavora con un modello salvato anziché con HTML grezzo:

curl -X POST https://api.mailpro.com/v2/send/campaign.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d "IDMessage=55" \
  -d "IDEmailExp=201" \
  -d "ListId=101" \
  -d "Campaign=1" \
  -d "TitleCampaign=April newsletter" \
  -d "DatePlanned=2026-05-01T09:00:00"

DatePlanned è facoltativo: se lo ometti, la campagna parte subito. Uno schema efficace è lasciare che l'agente scelga la lista, il modello e un orario di invio in base al fuso orario del pubblico, per poi mostrare il piano a una persona che lo approva. Le campagne programmate possono ancora essere spostate con PATCH /send/{IdSend}/reschedule.json o annullate con POST /send/{IdSend}/cancel.json.

Personalizzazione con i campi

In /send/sendmail, EmailData riceve l'indirizzo seguito da un massimo di 25 valori ([email protected],Alice,Dupont,Paris) che compilano i campi di personalizzazione del modello. Nelle campagne, i campi provengono dai dati di ciascun contatto della lista. L'agente deve solo inserire il campo nel suo HTML; l'API lo compila per ogni destinatario.

Importa contatti in blocco da un file caricato da un agente

Quando il primo passo di un flusso di lavoro è "aggiungi questi 500 nuovi lead", non fare 500 chiamate API. Invia un solo file:

curl -X POST https://api.mailpro.com/v2/import/upload.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -F "ListId=42" \
  -F "[email protected]" \
  -F "WebhookUrl=https://example.com/hooks/import-done"

Il file deve essere in UTF-8 con una riga di intestazione che includa Email; le altre colonne vengono associate ai campi personalizzati della lista. L'endpoint restituisce subito un ImportJobId, elabora il file in background e chiama il tuo WebhookUrl con il numero di righe importate, saltate e non valide.

Insidie e consigli

• Gli indirizzi disiscritti vengono rifiutati. L'API risponde "Email address unsubscribed." con un 400. Spiega all'agente che si tratta di un esito definitivo, non di un errore da ritentare.
• Tieni d'occhio i crediti. "Not enough credit available." arriva come 403. Iscriviti al webhook credits.low così una persona ricarica il credito prima che l'agente vada a sbattere contro il limite.
• Attenzione alla quota di richieste. Le chiamate API vengono conteggiate in una quota mensile condivisa dalle API Email, CRM e SMS (GET /account/limits.json). Limita le chiamate agli strumenti per conversazione e rallenta i tentativi in caso di 429.
• Resta su JSON. L'XML è supportato con il suffisso .xml, ma il JSON è più semplice per l'output degli strumenti di un LLM.
• Autentica il tuo dominio. Anche le email personalizzate scritte dall'AI hanno bisogno di SPF, DKIM e DMARC per arrivare nella casella di posta; consulta la nostra guida alla deliverability delle email.

Caso di studio (fittizio): "NovaFit", una catena di palestre con promemoria dei corsi scritti dall'AI

NovaFit gestisce 40 palestre e invia un promemoria 24 ore prima di ogni corso prenotato. In passato i promemoria erano un unico modello ("Ciao Anna, la tua lezione di yoga è domani alle 7:00"). Il team ha collegato Claude al sistema di prenotazione: per ogni promemoria, l'agente legge la frequenza recente dell'iscritto e il tipo di corso, scrive una riga personale ("La settimana scorsa hai mantenuto la posizione del guerriero per un minuto intero, pronta per il livello successivo?") e invia l'email con /send/sendmail. I bounce rientrano tramite il webhook email.bounced e vengono segnalati alla reception. Il tasso di apertura dei promemoria è salito dal 46% al 63% e la frequenza ai corsi è aumentata di 8 punti, senza alcuna variazione nel volume di email.

Prossimi passi

La Email API v2 gestisce l'invio. Se il tuo agente deve anche gestire contatti, tag, segmenti e campi personalizzati, leggi la nostra guida alla CRM API v3 per l'AI. Per i messaggi di testo, consulta come inviare SMS con un agente AI. Stai valutando una piattaforma gestita rispetto a un semplice servizio di invio? Consulta la nostra guida alle migliori alternative ad Amazon SES. Riferimento completo: la documentazione della Email API v2.