Inviare SMS con un agente AI tramite l'API SMS Mailpro™

L'email è il canale di default. L'SMS è il canale dell'urgenza. Quando il tuo agente AI deve avvisare un essere umano in pochi secondi — un'anomalia, un alert frode, un OTP, un aggiornamento di spedizione — l'SMS viene effettivamente letto entro un minuto. Questa guida mostra come collegare Claude, GPT o qualsiasi LLM con tool calling all'API SMS Mailpro™, sia per invii singoli che per campagne di massa.

In breve

L'API SMS Mailpro™ si autentica con id_client + api_key via HTTPS.

Usa /send/add_single.json per un SMS singolo e /send/add.json per invii di massa.

Numeri in formato internazionale E.164 (es. +393471234567) o con prefisso 00 — l'API accetta entrambi e memorizza la forma normalizzata.

Ogni endpoint è documentato in 20+ linguaggi sul nostro portale sviluppatori.

Dove l'SMS pilotato dall'AI ha davvero senso

Alert in tempo reale

La tua pipeline di monitoring rileva un picco di errori 5xx. Un agente AI legge l'anomalia, classifica la gravità e spara un SMS all'ingegnere di turno con contesto ("API v3 tasso errori ×12 negli ultimi 5 min, endpoint CRM coinvolti") — non un semplice bip di cercapersone. Diagnosi più rapida, meno alert fatigue.

OTP e flussi a due fattori

L'agente riceve una richiesta "autentica questo utente", genera un codice a 6 cifre, lo salva con scadenza e lo invia via SMS. L'utente lo digita, l'agente verifica. Oggi è un flusso custom; con il futuro endpoint Verify/OTP (vedi la roadmap API SMS) sarà una sola chiamata.

Fallback multicanale

L'email non è stata aperta in 2 ore, ma è urgente. L'agente ripiega su SMS — "Il tuo appuntamento è tra 1 ora" — usando la stessa scheda contatto da Mailpro™ v3. Orchestrazione cross-canale guidata dal ragionamento del LLM.

Campagne event-driven

Black Friday a mezzogiorno: l'agente sceglie l'audience con un criterio di freschezza ("clienti che hanno aperto un'email negli ultimi 14 giorni"), scrive un'offerta da 140 caratteri e lancia una campagna via /send/add.json. Offerta live in meno di un minuto, zero clic su dashboard.

Setup e modello di prezzo SMS

`id_client` + `api_key`

Stesso schema di auth dell'API email v2. Entrambi i valori sono nel tuo account Mailpro™ sotto Impostazioni → Accesso API. L'API SMS usa parametri in snake_case (id_client, non IdClient) — piccola differenza rispetto a v2, da segnalare nel system prompt dell'agente.

Crediti, tariffe per paese, saldo test

Gli SMS non hanno prezzo flat: il costo per messaggio dipende dal paese di destinazione. Controlla il saldo in qualsiasi momento:

curl "https://api.mailpro.com/sms/credit/get.json?id_client=YOUR_ID&api_key=YOUR_API_KEY"

Risposta:

{ "TotalCredits": 1476 }

Per i prezzi per paese, vedi i prezzi Mailpro.

Sandbox

Nessuna sandbox dedicata al momento — testa con piccoli volumi sul tuo account reale. Parti con /send/add_single.json verso il tuo numero prima di aprire il rubinetto del bulk.

Passo dopo passo: SMS singolo inviato da un agente AI

1. Schema dello strumento

tools = [{
    "name": "send_sms",
    "description": "Invia un SMS singolo a un numero via Mailpro.",
    "input_schema": {
        "type": "object",
        "properties": {
            "to":      {"type": "string", "description": "Numero in formato internazionale E.164, es +393471234567"},
            "message": {"type": "string", "description": "Corpo SMS, max 160 car. per segmento"}
        },
        "required": ["to", "message"]
    }
}]

2. Formattazione dei numeri

Usa il formato internazionale E.164: segno +, prefisso paese, numero nazionale, senza spazi né trattini. Anche il prefisso 00 al posto di + funziona. Esempi:

Italia: +393471234567
San Marino: +37866123456
Svizzera: +41791234567
Francia: +33671234567

Se l'agente riceve input grezzi ("347 123 4567"), normalizza prima di inviare — librerie come phonenumbers (Python) o libphonenumber-js (Node) lo fanno senza sforzo.

3. Chiamare `/send/add_single.json`

curl -X POST "https://api.mailpro.com/sms/send/add_single.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "to=+393471234567" \
  -d "message=Il tuo codice di verifica è 482913. Valido 10 min."

Risposta:

{
  "Result": "OK",
  "IdSend": 98765,
  "RemainingCredits": 1474
}

4. Stato di consegna dalla risposta

Result: "OK" significa che l'SMS è stato accettato dal gateway — non ancora consegnato al dispositivo. Per la conferma di consegna (DLR), ascolta il futuro webhook sms.delivered (vedi roadmap API SMS). Nel frattempo, RemainingCredits ti dice che l'invio è stato fatturato.

SMS di massa: raggiungere un'intera lista

Gestire liste di numeri (`/list`, `/phone`)

Le liste SMS sono l'equivalente delle rubriche email lato SMS. Endpoint per elencare, aggiungere, modificare, eliminare liste e numeri sono tutti sotto /list/*.json e /phone/*.json.

Inviare una campagna con `/send/add.json`

curl -X POST "https://api.mailpro.com/sms/send/add.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "id_list=11088" \
  -d "message=Black Friday: 30% di sconto fino a mezzanotte. mailp.ro/bf2026"

L'endpoint mette la campagna in coda e spara SMS a ogni numero della lista.

Programmato vs immediato

Aggiungi plan_date=2026-11-27T12:00:00 per programmare. Omettilo per l'invio immediato. L'agente può scegliere l'orario in base al fuso dei destinatari — ma attenzione al tempo aggregato: 10.000 SMS possono richiedere vari minuti per attraversare il gateway.

Stai costruendo un agente IA che invia SMS? I piani di Mailpro includono l’API SMS, i report di consegna e il volume necessario — a un prezzo prevedibile.

Importare numeri in massa via file

Come l'API email, anche l'API SMS ora espone un endpoint di upload file:

curl -X POST "https://api.mailpro.com/sms/import/upload.json" \
  -F "id_client=YOUR_ID" \
  -F "api_key=YOUR_API_KEY" \
  -F "id_list=11088" \
  -F "[email protected]" \
  -F "webhook_url=https://example.com/hooks/import-done"

La prima colonna del CSV deve chiamarsi Phone o PhoneNumber. I numeri sono normalizzati server-side; le voci non valide sono scartate (e riportate nel bilancio del job). Specifica completa nella sezione Import della reference SMS.

Esempi di codice

Python (agente → SMS con retry)

import anthropic, requests, time

def send_sms(to, message, retries=3):
    for attempt in range(retries):
        r = requests.post(
            "https://api.mailpro.com/sms/send/add_single.json",
            data={
                "id_client": MAILPRO_ID, "api_key": MAILPRO_KEY,
                "to": to, "message": message
            }
        )
        if r.status_code == 429:
            time.sleep(2 ** attempt)  # backoff esponenziale
            continue
        return r.json()
    raise Exception("Invio SMS fallito dopo i retry")

Node.js (webhook Express → Claude → SMS)

import express from "express";
import Anthropic from "@anthropic-ai/sdk";

const app = express();
const ai = new Anthropic();

app.post("/alert", async (req, res) => {
  const { severity, message } = req.body;
  const resp = await ai.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 256,
    tools: [/* schema send_sms */],
    messages: [{ role: "user", content: `Alert ${severity}: ${message}. Avvisa la reperibilità.` }]
  });
  for (const b of resp.content) {
    if (b.type === "tool_use") {
      await fetch(`https://api.mailpro.com/sms/send/add_single.json`, {
        method: "POST",
        body: new URLSearchParams({
          id_client: ID, api_key: KEY,
          to: b.input.to, message: b.input.message
        })
      });
    }
  }
  res.sendStatus(200);
});

cURL

curl -X POST "https://api.mailpro.com/sms/send/add_single.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "to=+393471234567" \
  -d "message=Il backup Mailpro è completato con successo alle 03:04 UTC."

Per la stessa chiamata in una ventina di altri linguaggi (PHP, Go, Ruby, C#, Java, Swift…), consulta la reference SMS — ogni endpoint propone lo snippet equivalente.

In arrivo: Verify/OTP e Phone Lookup

Due feature della roadmap API SMS sono particolarmente utili per integrazioni di agenti AI:

Endpoint Verify / OTP

Invece di costruire il tuo flusso OTP (genera codice, salva, invia, verifica), i futuri endpoint /verify/start e /verify/check faranno tutto: generazione codice, hashing, rate limit, template multilingua, conteggio tentativi. L'agente chiama solo /verify/start e poi /verify/check.

HLR Phone Lookup

Il futuro endpoint /phone/lookup restituirà in tempo reale info sull'operatore (mobile / fisso / voip), portabilità (MNP), raggiungibilità. Fondamentale per pulire le liste lead prima di una campagna SMS — inutile inviare a un numero disattivato.

Entrambe le feature useranno lo stesso modello di auth, rendendole subito consumabili da un agente AI.

Consigli e insidie

Risposte in PascalCase (come v2 email)

L'API SMS Mailpro™ restituisce Result, IdSend, RemainingCredits — PascalCase. Coerente con v2 email, diverso da v3 CRM (snake_case). Da precisare nel system prompt.

Gestione STOP e suppression dei numeri

Gli utenti possono rispondere STOP per disiscriversi. Oggi il nostro gateway lo gestisce e blocca gli invii futuri in automatico. Il futuro endpoint /suppressions esporrà la lista di suppression come risorsa API — per audit e gestione manuale.

GDPR e consenso

Ottieni sempre un consenso esplicito prima di inviare SMS marketing. Per gli SMS transazionali (OTP, alert innescati da azione utente), il consenso è implicito. L'agente non deve decidere se un utente è opt-in — è una decisione legale, non di prompting.

Caso studio (fittizio): "VeloCorriere" — consegne in bici a Milano con SMS di ETA guidati da AI

VeloCorriere consegna cibo e pacchi a Milano. Storicamente il cliente riceveva un SMS "il tuo corriere è in arrivo" al pickup, e basta. Il team ha collegato Claude dietro il sistema di dispatch: non appena il GPS del rider mostrava meno di 500 m dal drop-off, l'agente lanciava un SMS Mailpro™ con un testo su misura in base al tipo d'ordine ("Il tuo caffè arriva tra 2 minuti — sii alla porta"). L'NPS cliente sull'arrivo è salito di 18 punti. Il volume SMS è cresciuto del 30%, rimanendo ampiamente sotto i risparmi su chiamate al supporto. Il team dispatch controlla i messaggi inviati dall'agente nello storico Mailpro™; ogni tanto aggiusta il prompt quando il tono non è del tutto giusto.

Prossimo passo

L'SMS è l'ultimo grande canale dello stack Mailpro™. Se non hai ancora letto la guida pilastro su agenti AI e Mailpro, parti da lì per la visione d'insieme. Per le guide email, vedi Email transazionali v2 e CRM v3.

Reference: API SMS Mailpro. Prezzi: prezzi Mailpro.

FAQ

Un agente AI può inviare OTP via Mailpro?

Oggi sì, artigianalmente: genera un codice a 6 cifre, salvalo con scadenza, invialo via /send/add_single.json. Molto presto un endpoint dedicato /verify/start + /verify/check farà tutto in una sola chiamata. Vedi roadmap API SMS.

Quanto costa un SMS?

Varia per paese di destinazione. Vedi prezzi per la tariffa attuale.

L'API supporta numeri internazionali?

Sì, Mailpro™ invia in 200+ paesi. Usa il formato E.164 (+<prefisso><numero>, es. +393471234567) o il prefisso 00 equivalente — l'API accetta entrambi.

Come blocco un numero che ha risposto STOP?

Oggi è automatico a livello di gateway. Il futuro endpoint /suppressions permetterà di elencare, aggiungere e rimuovere i numeri in suppression via API — utile per sincronizzare con il tuo database di preferenze.

Mailpro e l’API SMS

Lascia che il tuo agente IA invii SMS — al resto pensa Mailpro

Collega il tuo agente IA all’API SMS di Mailpro e potrà inviare SMS da solo — promemoria, avvisi, conferme. A te la copertura e i report; scopri quanto costa farlo funzionare.

Inizia gratis con Mailpro Scopri i prezzi di Mailpro