Best Practice

Una checklist breve e con un punto di vista preciso per usare in produzione la SMS API di Agile Telecom.

Throughput e Rate Limiting

Throughput REST sostenuto — Stima qualche centinaio di submission al secondo per API key di default. Per volumi superiori, chiedi al team wholesale di alzare il limite o passa a SMPP.
SMPP per volumi alti — Un singolo bind SMPP TRX sostiene affidabilmente migliaia di TPS. Combina fino a 4 bind per account; vedi il reference SMPP.
Back-off sui 429 — Implementa back-off esponenziale con jitter quando ricevi 429 Too Many Requests. Non ritentare più rapidamente di quanto indichino gli header.
Batch in una sola chiamata — Quando hai molte destinazioni con lo stesso body, invia una richiesta unica con più destinations invece di una request per numero.

Idempotenza — Imposta un globalId stabile sulla richiesta e ids stabili per messaggio. Se una richiesta fallisce prima che tu possa leggere la risposta, puoi ritentarla in sicurezza se l'app controlla l'esistenza del globalId.
Codici ritentabili — 408, 429, 5xx. Tutto il resto è un errore permanente per quella send.
Limita i retry — Al massimo 3 tentativi con back-off. Oltre questo, allerta e fermati — il problema è upstream.

Implementa sempre l'opt-out per il traffico marketing. Il minimo è gestire le parole chiave STOP / STOP ALL in inbound (vedi SMS in ingresso).
Persisti lo stato di opt-out nel tuo database, chiavato per numero, e consultalo prima di ogni invio.
Linguaggio "one-click STOP" — Includi Rispondi STOP per disiscriverti (o equivalente locale) negli SMS marketing. Alcuni paesi lo rendono obbligatorio.
Orari silenziosi — Rispetta le regole locali sugli orari notturni (tipicamente 21:00 → 09:00 ora locale).

Valida prima di inviare — Usa MNP lookup per rilevare numeri invalidi o portati; risparmi denaro e migliori i KPI di consegna.
Scarta la spazzatura presto — Numeri vuoti, troppo corti, non internazionali.
Credit check — Usa l'endpoint credit-check per campagne grandi per rilevare "finirai il credito al messaggio 47k" prima di partire.

Scegli GSM-7 quando possibile — Un carattere non-GSM (un'emoji, un « di passaggio) sposta tutto il messaggio su UCS-2 e dimezza la lunghezza per parte. Sostituisci o rimuovi se non ti serve.
Tieni i transazionali in una sola parte — 160 GSM-7 o 70 UCS-2. Un SMS transazionale in due parti raddoppia il costo senza valore aggiunto per OTP e conferme.
Sender ID — Pre-registra i sender alfanumerici nei paesi che lo richiedono (Italia, India, Francia, EAU, ecc.). Altrimenti i messaggi possono essere riscritti o silenziosamente scartati.

Logga ogni submission con globalId, id, destinazione e timestamp.
Collega i DLR allo stesso record — Riconcilia l'id loggato in submission con il DLR che arriva dopo.
Traccia questi KPI:
- Tasso accepted in submission (deve essere prossimo al 100%).
- Tasso DLR DELIVERED per operatore e paese.
- Tempo medio submit → stato finale DLR.
- Tassi REJECTED e UNDELIVERABLE (anomalie indicano spesso problemi di sender ID).

API key solo in variabili d'ambiente, mai in codice client o repository.
Ruota le key ogni 90 giorni in account ad alto traffico.
IP whitelist dell'IP outbound del tuo backend.
Solo HTTPS — Dal 15 gennaio 2026 l'HTTP in chiaro viene rifiutato. Audita ora i client legacy.

Definisci un unico servizio SMS di proprietà nella tua architettura — ogni team chiama quello, non la piattaforma direttamente.
Cache lo stato di opt-out, la configurazione dei sender ID e i record DLR lì.
Esponi metriche così l'on-call vede cali di deliverability prima degli utenti.
Simula prima del lancio — Usa simulation: true sulla send per fare dry-run del payload a scala.