L’API Oblic consente ai server di inviare email, SMS e WhatsApp per conto dell’organizzazione e verificarne gli esiti, registrare le azioni dei contatti nei propri sistemi e gestire modelli, identità mittente, liste di contatti, webhook e sottoaccount utilizzati. I server la chiamano con una chiave API.
Il documento OpenAPI di questa versione è external-v1.json: descrive tutte le rotte, gli ambiti richiesti e i corpi accettati, visualizzati nella documentazione OpenAPI. API v2 usa token di accesso OAuth anziché chiavi API.
Tutti i percorsi iniziano con https://api.oblic.app/external/v1, tranne quelli precedenti delle liste di contatti, che iniziano con https://api.oblic.app/external/contact-list/v1.
Inviare una chiave API come Authorization: Bearer <key>. Le chiavi si creano in Impostazioni → Integrazione API, ciascuna con gli ambiti necessari. Conservarle sui server: una chiave in un browser o in un’app mobile è leggibile da chiunque. Vedere Autenticazione.
Le risposte con corpo usano un involucro JSON:{"status": "success", "data": …, "errors": null}, oppure "status": "error" con gli errori, ciascuno con codice (cd) e messaggio. Vedere Errori.
Una piattaforma opera per i propri clienti tramite sottoaccount: una chiave e il cliente indicato in X-Oblic-On-Behalf-Of a ogni richiesta.
Riprovare finché lo stato della chiave è conservato, con lo stesso Idempotency-Key e corpo. Le chiavi email e WhatsApp restano in Redis per 24 ore; perdita o scadenza della cache può consentire un altro invio. La chiave SMS resta nella riga del messaggio memorizzato senza scadenza temporale. Non è una garanzia permanente di esecuzione esattamente una volta. Vedere Messaggi.
Una richiesta di invio riuscita indica accettazione, non consegna da parte del fornitore. La consegna richiede invii in uscita abilitati, consumer attivi e fornitori configurati. Una richiesta accettata in un’installazione con invii in uscita disabilitati non significa che il messaggio verrà inviato. Non è garantito un termine di consegna.
I timestamp di risposta che identificano un istante includono uno scostamento ISO 8601. Ad esempio, 2026-10-30T20:00:00Z e 2026-10-31T01:30:00+05:30 identificano lo stesso istante. Interpretare lo scostamento prima di mostrare l’ora nel fuso del lettore. new Date(value) in JavaScript e OffsetDateTime.parse(value) in Java lo fanno; aggiungere Z a un valore senza scostamento o interpretare un istante come LocalDateTime no.
Un valore composto solo da una data rimane una data. Una pianificazione esplicitamente locale ha un contratto distinto: l’ora è associata a un campo di fuso orario, non interpretata da sola come un istante.
«Permessi» indica l’ambito che la chiave deve possedere per la rotta; se ne sono elencati più di uno, ne basta uno. Alcune rotte richiedono anche una chiave con ruolo Proprietario o Amministratore. Ambito e ruolo concedono il permesso, ma configurazione del servizio e idoneità della risorsa possono ancora causare un rifiuto.
Messaggi API
Metodo
Percorso
Funzione
Permessi
GET
/external/v1/messages
Messaggi inviati tramite API, dal più recente
messages:read
POST
/external/v1/messages/email
Inviare un’email da un mittente verificato, con HTML proprio o un modello
email:send
POST
/external/v1/messages/sms
Inviare un SMS corrispondente a un modello DLT dell’account
sms:send
POST
/external/v1/messages/whatsapp
Inviare un modello WhatsApp approvato o una risposta entro 24 ore
whatsapp:send
GET
/external/v1/messages/{messageId}
Un messaggio inviato tramite API e il suo esito
messages:read
Rapporti
Metodo
Percorso
Funzione
Permessi
GET
/external/v1/reports/summary
Esiti dei messaggi inviati in un periodo, per canale e stato
messages:read
Modelli email
Metodo
Percorso
Funzione
Permessi
GET
/external/v1/templates
Modelli email dell’account, dal più recente
email:send oppure templates:manage
POST
/external/v1/templates
Creare un modello email da HTML
templates:manage, chiave Proprietario o Amministratore
GET
/external/v1/templates/{id}
Un modello email con HTML e variabili ammesse
email:send oppure templates:manage
PUT
/external/v1/templates/{id}
Sostituire un modello email creato da HTML
templates:manage, chiave Proprietario o Amministratore
DELETE
/external/v1/templates/{id}
Eliminare un modello email
templates:manage, chiave Proprietario o Amministratore
Intestazioni e modelli SMS
Solo gli account di registro configurati possono modificare il registro SMS, anche con ambito e ruolo richiesti. Queste rotte memorizzano intestazioni e modelli già registrati presso DLT; non li registrano presso DLT. Gli elenchi includono modelli approvati anche inattivi; l’invio richiede ulteriori controlli di idoneità.
Metodo
Percorso
Funzione
Permessi
GET
/external/v1/sms/account
Limiti SMS dell’account e invii effettuati nel mese
sms:send oppure templates:manage
GET
/external/v1/sms/senders
Intestazioni DLT dell’account
sms:send oppure templates:manage
GET
/external/v1/sms/templates
Modelli DLT dell’account
sms:send oppure templates:manage
POST
/external/v1/sms/templates
Memorizzare in Oblic un modello già registrato presso DLT
templates:manage, chiave Proprietario o Amministratore
PUT
/external/v1/sms/senders/{senderId}
Memorizzare un’intestazione DLT o cambiarne l’impostazione predefinita
templates:manage, chiave Proprietario o Amministratore
DELETE
/external/v1/sms/senders/{senderId}
Eliminare un’intestazione DLT
templates:manage, chiave Proprietario o Amministratore
PUT
/external/v1/sms/templates/{id}
Modificare un modello DLT
templates:manage, chiave Proprietario o Amministratore
DELETE
/external/v1/sms/templates/{id}
Eliminare un modello DLT
templates:manage, chiave Proprietario o Amministratore
PUT
/external/v1/sms/templates/{id}/sharing
Consentire l’invio di un modello a nessun sottoaccount, a tutti o a quelli indicati
templates:manage, chiave Proprietario o Amministratore
Numero e modelli WhatsApp
Metodo
Percorso
Funzione
Permessi
GET
/external/v1/whatsapp/connection
Numero WhatsApp collegato all’account
whatsapp:send oppure templates:manage
POST
/external/v1/whatsapp/connection
Collegare o sostituire il numero WhatsApp Business dell’account
templates:manage, chiave Proprietario o Amministratore
DELETE
/external/v1/whatsapp/connection
Scollegare il numero WhatsApp dell’account
templates:manage, chiave Proprietario o Amministratore
GET
/external/v1/whatsapp/templates
Modelli WhatsApp dell’account con l’esito della revisione Meta
whatsapp:send oppure templates:manage
POST
/external/v1/whatsapp/templates
Sottoporre un modello WhatsApp alla revisione di Meta
templates:manage, chiave Proprietario o Amministratore
GET
/external/v1/whatsapp/recipients/{number}
Cosa l’account può inviare ora a un numero
whatsapp:send oppure templates:manage
Identità mittente
Metodo
Percorso
Funzione
Permessi
GET
/external/v1/identities
Domini e indirizzi mittente e relativo stato di verifica
email:send oppure identities:manage
POST
/external/v1/identities
Aggiungere un dominio o indirizzo mittente da verificare
identities:manage
DELETE
/external/v1/identities/{identityId}
Eliminare un’identità mittente
identities:manage
Liste di contatti
Metodo
Percorso
Funzione
Permessi
POST
/external/contact-list/v1/add
Creare una lista di contatti
contacts:manage
POST
/external/contact-list/v1/{contactListId}/add
Aggiungere contatti a una lista
contacts:manage
GET
/external/contact-list/v1/{nextIndex}/{limit}
Liste di contatti dell’account, una pagina alla volta
contacts:manage
Eventi
Metodo
Percorso
Funzione
Permessi
POST
/external/v1/events
Registrare fino a 100 eventi dei contatti, come ordini e carrelli abbandonati
events:write
Webhook API
Metodo
Percorso
Funzione
Permessi
GET
/external/v1/webhooks
Endpoint webhook dell’organizzazione
webhooks:manage, chiave Proprietario o Amministratore
POST
/external/v1/webhooks
Registrare un endpoint webhook o trovare quello della stessa URL
webhooks:manage, chiave Proprietario o Amministratore
GET
/external/v1/webhooks/deliveries
Consegne fallite, dalla più recente
webhooks:manage, chiave Proprietario o Amministratore
GET
/external/v1/webhooks/{webhookId}
Un endpoint webhook
webhooks:manage, chiave Proprietario o Amministratore
PUT
/external/v1/webhooks/{webhookId}
Cambiare URL o tipi di evento di un endpoint
webhooks:manage, chiave Proprietario o Amministratore
DELETE
/external/v1/webhooks/{webhookId}
Interrompere le consegne a un endpoint
webhooks:manage, chiave Proprietario o Amministratore