Messaggi dell'API
Invia email, SMS e messaggi WhatsApp per la tua organizzazione, usa una chiave di idempotenza per riprovare entro i limiti di conservazione documentati e consulta l'esito di ogni messaggio, singolarmente o in un rapporto.
Queste route /external/v1 usano chiavi API. Ogni invio richiede una chiave con l'ambito del canale: email:send, sms:send o whatsapp:send. La lettura di messaggi e rapporti richiede messages:read. Consulta Autenticazione; i token di accesso OAuth usano API v2.
Un invio riuscito risponde normalmente con 202 Accepted, il proprio identificativo e lo stato. L'accettazione non equivale alla consegna del provider: l'invio richiede l'abilitazione della consegna in uscita, i consumer del canale in esecuzione e la configurazione del relativo provider. Non è garantito alcun tempo di consegna. Nelle installazioni con consegna in uscita disabilitata, una richiesta accettata non significa che il messaggio verrà inviato. Il suo identificativo, msg_ seguito da 32 caratteri esadecimali, permette di leggerne l'esito qui o in un webhook.
202 Accettato
{
"status": "success",
"data": { "id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60", "status": "queued" },
"errors": null
}
Inviare un'email
Un'email parte da una delle identità del mittente verificate della tua organizzazione, con HTML proprio oppure generato da uno dei tuoi modelli email.
- Nome
to- Tipo
- string[]
- Descrizione
Facoltativo se
ccobccfornisce destinatari. Inserisci da 1 a 50 voci di indirizzo complessive trato,ccebcc; ogni singolo elenco può essere assente o vuoto. Un totale vuoto viene rifiutato suto.
- Nome
cc- Tipo
- string[]
- Descrizione
Indirizzi per l'intestazione Cc. Ricevono lo stesso contenuto dell'email degli altri destinatari.
- Nome
bcc- Tipo
- string[]
- Descrizione
Indirizzi dell'elenco di consegna Bcc. Bcc non è nascosto nei record dei messaggi e nei webhook del mittente.
- Nome
from- Tipo
- string
- Descrizione
L'indirizzo di un'identità verificata oppure qualsiasi indirizzo di un'identità di dominio verificata. Se omesso, è necessario il mittente principale verificato dell'organizzazione; non viene scelta un'altra identità verificata come alternativa. Quando Oblic invia per conto di un'identità, l'indirizzo Da visibile è un alias sul dominio di invio configurato di Oblic, non l'indirizzo dell'identità.
- Nome
fromName- Tipo
- string
- Descrizione
Il nome del mittente, fino a 255 caratteri, senza
<,>,"o interruzioni di riga. Se omesso, viene usato il nome visualizzato dell'identità. Oblic aggiungevia Oblicquando invia per conto dell'identità.
- Nome
replyTo- Tipo
- string
- Descrizione
L'indirizzo a cui arrivano le risposte. Quando Oblic invia per conto di un'identità, le risposte vanno all'indirizzo originale verificato, salvo un valore diverso in
replyTo.
- Nome
subject- Tipo
- string
- Descrizione
Fino a 1,023 caratteri. Obbligatorio con
html. ContemplateId, se non lo specifichi viene usato l'oggetto del modello.
- Nome
html- Tipo
- string
- Descrizione
L'HTML dell'email, inviato così come fornito. Specifica
htmloppuretemplateId, mai entrambi.
- Nome
text- Tipo
- string
- Descrizione
Una versione di testo semplice, inviata insieme all'HTML per i client che mostrano il testo. Con
templateId, i segnaposto{{name}}vengono compilati davariablescosì come sono, senza escape.
- Nome
templateId- Tipo
- string
- Descrizione
L'identificativo del modello email da inviare, composto da 18 lettere e cifre ASCII.
- Nome
variables- Tipo
- object
- Descrizione
Con
templateId, un valore per ciascun segnaposto{{name}}del modello: al massimo 100, ciascuno una stringa di massimo 10,000 caratteri. I nomi corrispondono indipendentemente dalle maiuscole. Nei punti dell'HTML in cui viene inserito, il valore subisce l'escape HTML: il testo inviato come<b>viene quindi mostrato come<b>.
- Nome
attachments- Tipo
- object[]
- Descrizione
Al massimo 10 file, ciascuno come
{"fileName": …, "content": …}con i byte del file in base64, per un totale massimo di 10 MB. Possono essere accettati file come archivi ZIP, CSV e ICS; vengono rifiutate le estensioni vietate da SES e i contenuti eseguibili rilevati. I caricamenti delle campagne conservano la loro lista di consentiti separata.
- Nome
metadata- Tipo
- object
- Descrizione
Le tue stringhe associate a chiavi, come l'identificativo dell'ordine o del tenant, restituite con il messaggio e ogni suo webhook, ma mai inviate. Consulta Metadati.
Tutti e tre gli elenchi di destinatari ricevono lo stesso contenuto. Gli indirizzi To e Cc sono visibili nelle intestazioni dei destinatari; gli indirizzi Bcc continuano a comparire nell'elenco dei messaggi e nei webhook del mittente. Il registro non memorizza un ruolo To/Cc/Bcc per destinatario.
Questi elenchi richiedono versioni compatibili dell'API e del mittente Functions. Attiva il mittente aggiornato prima dell'API o insieme a essa. La scansione degli allegati è un controllo configurato separatamente; l'accettazione non dimostra che un file sia stato analizzato o che sia privo di malware.
Un'email con HTML proprio
curl -X POST https://api.oblic.app/external/v1/messages/email \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-1042-confirmation' \
-d '{
"from": "orders@example.com",
"fromName": "Example Store",
"to": ["asha@example.org"],
"subject": "Your order is confirmed",
"html": "<p>Thank you for your order.</p>"
}'
Un'email da un modello
curl -X POST https://api.oblic.app/external/v1/messages/email \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"to": ["asha@example.org"],
"templateId": "TEM000R7ZM4Q2VXH00",
"text": "Hi {{first_name}}, your order {{order_id}} is confirmed.",
"variables": { "first_name": "Asha", "order_id": "1042" }
}'
I destinatari che hanno annullato l'iscrizione o si trovano nell'elenco di soppressione vengono saltati: per loro il messaggio è skipped e una notifica email.suppressed tramite webhook ne indica il motivo.
| Rifiuto | cd | Quando |
|---|---|---|
| 400 | il campo, ad esempio TO[0] | Un campo è mancante o non valido; un insieme combinato di destinatari vuoto o troppo grande viene rifiutato su to |
| 400 | INVALID_REQUEST | Non viene fornito nessuno tra html e templateId, oppure vengono forniti entrambi; sono presenti variables senza modello oppure manca l'oggetto |
| 400 | INVALID_VARIABLES | Un segnaposto non ha valore, un nome compare due volte con maiuscole diverse oppure l'oggetto compilato è troppo lungo |
| 400 | INVALID FILE | Un allegato è troppo grande o di un tipo non accettato |
| 403 | EMAIL_SUSPENDED | Le email dell'account sono sospese per mancati recapiti o segnalazioni di spam, fino alla riattivazione da parte dell'assistenza Oblic |
| 413 | MESSAGE_TOO_LARGE | L'email è troppo grande per essere accodata |
| 422 | UNVERIFIED_SENDER | from non appartiene a un'identità verificata; il messaggio elenca quelle verificate |
| 422 | TEMPLATE_NOT_FOUND | Non esiste un modello email con quell'identificativo |
| 422 | TEMPLATE_HAS_MENTIONS | Il modello contiene menzioni della dashboard, come @unsubscribe, compilate soltanto da campagne e automazioni |
| 429 | RATE_LIMITED | Superamento del limite orario dell'account (5,000 destinatari per impostazione predefinita) o del limite per un indirizzo (10 all'ora per impostazione predefinita); ogni invio conta i destinatari distinti canonicalizzati nei tre elenchi, quindi un indirizzo ripetuto in quell'invio conta una volta. Retry-After indica quando |
| 429 | QUOTA_EXCEEDED | È superato il numero di messaggi mensili dell'account (100,000 per impostazione predefinita); Retry-After indica quando riprovare |
Con il worker di reputazione abilitato, i valori predefiniti configurabili esaminano le email di ciascun account negli ultimi 7 giorni dopo l'invio a 500 destinatari: al 2% di mancati recapiti o allo 0.05% di segnalazioni di spam vengono avvisati i proprietari; al 4% o allo 0.08% le email vengono sospese fino alla riattivazione da parte dell'assistenza Oblic. Con questi valori, le segnalazioni di spam vengono valutate solo dopo l'invio a 1,251 destinatari: una sola segnalazione non sospende quindi un account. Contano soltanto i mancati recapiti permanenti, una volta per destinatario. Un worker in pausa o disabilitato non esegue questa verifica periodica. Durante la sospensione, un'email viene rifiutata con EMAIL_SUSPENDED; un'email già accettata ma non ancora inviata fallisce con un evento email.failed il cui failureCode è EMAIL_SUSPENDED.
Inviare un SMS
Un SMS viene inviato a un numero di cellulare indiano e deve corrispondere a uno dei modelli DLT consentiti per l'account: il testo fisso del modello deve coincidere esattamente e ogni variabile deve essere compilata. Fornisci il testo e Oblic individua il modello, oppure fornisci l'identificativo DLT del modello e le sue variabili.
- Nome
to- Tipo
- string
- Descrizione
Obbligatorio:
+91e dieci cifre, con la prima da 6 a 9. Spazi e trattini vengono ignorati.
- Nome
text- Tipo
- string
- Descrizione
Il messaggio, fino a 2,000 caratteri, deve essere uno dei tuoi modelli con le variabili compilate: ogni variabile occupa da 1 a 30 caratteri su una sola riga. Il testo con caratteri non ASCII semplici, come
éo₹, corrisponde soltanto a modelli Unicode.
- Nome
templateId- Tipo
- string
- Descrizione
Al posto di
text: l'identificativo DLT del modello, fino a 32 cifre.
- Nome
variables- Tipo
- string[]
- Descrizione
Con
templateId: un valore per ogni variabile del modello, nell'ordine, fino a 30 valori. Ogni valore occupa da 1 a 30 caratteri su una sola riga, in ASCII semplice salvo che il modello sia Unicode.
- Nome
senderId- Tipo
- string
- Descrizione
L'intestazione DLT del mittente, fino a 11 caratteri, che deve appartenere al modello. Se omessa, viene preferita l'intestazione predefinita dell'account.
- Nome
purpose- Tipo
- string
- Descrizione
otp,transactional(predefinito) oppurepromotional. Un messaggio promozionale corrisponde soltanto a modelli promozionali; gli altri soltanto a modelli non promozionali.
- Nome
unicode- Tipo
- boolean
- Descrizione
trueper considerare soltanto i modelli Unicode.
- Nome
metadata- Tipo
- object
- Descrizione
Le tue stringhe associate a chiavi, come l'identificativo dell'ordine o del tenant, restituite con il messaggio e ogni suo webhook, ma mai inviate. Consulta Metadati.
Un messaggio SMS
curl -X POST https://api.oblic.app/external/v1/messages/sms \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: login-7731' \
-d '{
"to": "+919812345678",
"text": "Your Example code is 482913. It is valid for 10 minutes.",
"purpose": "otp"
}'
Un segmento contiene fino a 160 unità GSM-7; i caratteri di estensione come ^ contano doppio. Un SMS Unicode contiene invece fino a 70 unità di codice UTF-16: un carattere esterno al piano multilingue di base ne usa due. I messaggi più lunghi usano segmenti di 153 unità GSM-7 oppure 67 unità di codice UTF-16. Un SMS promozionale può essere inviato soltanto dalle 10:00 incluse alle 21:00 escluse, ora dell'India. I codici di accesso, gli SMS transazionali e quelli di servizio non vengono rifiutati per un portafoglio vuoto.
| Rifiuto | cd | Quando |
|---|---|---|
| 400 | INVALID_NUMBER | to non è un numero di cellulare indiano |
| 400 | INVALID_REQUEST | Non viene fornito nessuno tra text e templateId, oppure vengono forniti entrambi |
| 400 | INVALID_VARIABLES | Le variabili non corrispondono al modello |
| 402 | INSUFFICIENT_BALANCE | L'SMS è promozionale e il portafoglio che paga per l'account è vuoto |
| 422 | TEMPLATE_NOT_REGISTERED | Il testo o il templateId non corrisponde a nessun modello consentito per l'account oppure a nessuno sotto senderId |
| 422 | SENDER_NOT_ALLOWED | senderId non è l'intestazione di alcun modello consentito per l'account |
| 422 | MESSAGE_TYPE_NOT_ENABLED | Il tipo del modello non viene inviato da Oblic: i tipi inviati sono i messageTypes dell'account, per impostazione predefinita soltanto service_implicit |
| 422 | URL_NOT_WHITELISTED | Una variabile contiene un collegamento il cui dominio non è nella lista consentita DLT |
| 422 | OUTSIDE_PROMOTIONAL_HOURS | Un SMS promozionale fuori dall'intervallo 10:00–21:00, ora dell'India; Retry-After indica quando riprovare |
| 429 | RATE_LIMITED | È superato il limite orario dell'account (1,000 messaggi per impostazione predefinita) oppure quello verso un singolo numero (10 all'ora per impostazione predefinita); Retry-After indica quando riprovare |
| 429 | QUOTA_EXCEEDED | È superato il numero di segmenti mensili dell'account (10,000 per impostazione predefinita); Retry-After indica quando riprovare |
| 503 | SMS_UNAVAILABLE | Al momento non è possibile accodare l'SMS: riprova con lo stesso Idempotency-Key; oppure gli SMS non sono configurati su questa installazione Oblic |
GET /external/v1/sms/account mostra i limiti dell'account, i tipi di modello inviati da Oblic e quanto è stato inviato questo mese.
Inviare un messaggio WhatsApp
Un messaggio WhatsApp parte dal numero collegato all'account: un modello approvato oppure una risposta libera entro 24 ore dall'ultimo messaggio ricevuto dalla persona.
- Nome
to- Tipo
- string
- Descrizione
Obbligatorio: il numero in formato internazionale, ad esempio
+919812345678.
- Nome
template- Tipo
- string
- Descrizione
Il nome di uno dei tuoi modelli WhatsApp, come è stato creato. Specifica
templateoppuretext, mai entrambi.
- Nome
language- Tipo
- string
- Descrizione
La lingua del modello, ad esempio
enohi;enper impostazione predefinita.
- Nome
variables- Tipo
- string[]
- Descrizione
I valori per
{{1}},{{2}}e gli altri segnaposto del modello, nell'ordine: al massimo 30, ciascuno di massimo 1,024 caratteri.
- Nome
headerVariables- Tipo
- string[]
- Descrizione
I valori delle variabili dell'intestazione testuale del modello, nell'ordine: al massimo 5, ciascuno di massimo 1,024 caratteri.
- Nome
headerMediaUrl- Tipo
- string
- Descrizione
Il collegamento https dell'immagine, del video o del documento inviato dall'intestazione del modello, fino a 2,048 caratteri. Se omesso, l'intestazione invia il contenuto multimediale con cui il modello è stato approvato.
- Nome
text- Tipo
- string
- Descrizione
Una risposta libera, fino a 4,096 caratteri, inviabile soltanto entro 24 ore dall'ultimo messaggio della persona al tuo numero.
- Nome
metadata- Tipo
- object
- Descrizione
Le tue stringhe associate a chiavi, come l'identificativo dell'ordine o del tenant, restituite con il messaggio e ogni suo webhook, ma mai inviate. Consulta Metadati.
Un modello WhatsApp
curl -X POST https://api.oblic.app/external/v1/messages/whatsapp \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"to": "+919812345678",
"template": "order_shipped",
"language": "en",
"variables": ["Asha", "1042"]
}'
L'intestazione di un modello viene compilata come il corpo. headerVariables compila le variabili di un'intestazione testuale, mentre headerMediaUrl fornisce l'immagine, il video o il documento di un'intestazione multimediale; altrimenti viene inviato quello approvato con il modello. Un modello che richiede elementi non inviabili dall'API, come un'intestazione con posizione, un pulsante con valore proprio o una variabile denominata come {{first_name}}, viene rifiutato prima di qualsiasi invio o addebito.
Un modello con immagine nell'intestazione
curl -X POST https://api.oblic.app/external/v1/messages/whatsapp \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"to": "+919812345678",
"template": "diwali_sale",
"headerMediaUrl": "https://cdn.example.com/diwali.jpg",
"variables": ["20%"]
}'
GET /external/v1/whatsapp/recipients/{number} indica se un numero ha revocato il consenso al marketing e fino a quando è possibile inviare una risposta libera.
| Rifiuto | cd | Quando |
|---|---|---|
| 400 | INVALID_REQUEST | Non viene fornito nessuno tra template e text, oppure vengono forniti entrambi, o si usa headerVariables o headerMediaUrl con text |
| 402 | INSUFFICIENT_BALANCE | Il modello è di marketing e il portafoglio che paga per l'account è vuoto |
| 422 | INVALID_NUMBER | to non è un numero in formato internazionale |
| 422 | WHATSAPP_NOT_CONNECTED | L'account non ha un numero WhatsApp collegato |
| 422 | TEMPLATE_NOT_FOUND | L'account non ha un modello con quel nome e quella lingua |
| 422 | TEMPLATE_NOT_APPROVED | Meta non ha approvato il modello |
| 422 | INVALID_VARIABLES | Il numero di variabili non corrisponde al corpo o all'intestazione testuale del modello; oppure si usa headerVariables per un'intestazione multimediale o headerMediaUrl per un'intestazione che non lo è |
| 422 | MEDIA_REQUIRED | L'intestazione del modello è un'immagine, un video o un documento e headerMediaUrl non è un collegamento https; oppure, se omesso, neppure il contenuto multimediale approvato con il modello ha un collegamento https |
| 422 | TEMPLATE_NOT_SENDABLE | Il modello richiede elementi non inviabili dall'API: un'intestazione con posizione, un pulsante con valore proprio o una variabile denominata |
| 422 | RECIPIENT_OPTED_OUT | Un modello di marketing è destinato a un numero che ha revocato il consenso |
| 422 | OUTSIDE_SESSION_WINDOW | Una risposta libera oltre 24 ore dall'ultimo messaggio della persona |
Riprovare un invio
Invia un'intestazione Idempotency-Key con ogni invio: da 1 a 255 caratteri a tua scelta, ad esempio l'identificativo di un ordine o evento. In caso di timeout o se non sai se l'invio sia stato accettato, ripeti con la stessa chiave e lo stesso corpo. La deduplicazione dipende dallo stato della chiave conservato, non è una garanzia permanente contro ogni richiesta ripetuta:
- Ripetere lo stesso invio restituisce
202con l'identificativo del primo messaggio, senza inviarlo due volte. - La stessa chiave con un messaggio diverso, compresi i suoi
metadata, viene rifiutata con409 IDEMPOTENCY_CONFLICT, senza accodare nulla. - Durata di una chiave: lo stato delle chiavi email e WhatsApp è conservato in Redis per 24 ore; la perdita o la scadenza della cache elimina quello stato di deduplicazione e la stessa chiave può quindi inviare di nuovo. Una chiave SMS non ha scadenza temporale nella riga del messaggio memorizzata: un SMS successivo richiede una propria chiave. Questi limiti non garantiscono la consegna.
- Le chiavi appartengono alla tua organizzazione, con un insieme per canale: la stessa chiave può quindi essere usata per un'email e un SMS. Con
X-Oblic-On-Behalf-Of, appartengono al sottoaccount. - Ogni tentativo viene nuovamente validato prima della ricerca della chiave: un'email il cui mittente non è più verificato o una risposta WhatsApp oltre le 24 ore viene rifiutata, invece di restituire il primo identificativo.
Una chiave vuota o più lunga di 255 caratteri produce 400 INVALID_IDEMPOTENCY_KEY.
Per l'email, gli elenchi cc e bcc non vuoti fanno parte dell'hash di idempotenza, anche se i loro indirizzi compaiono anche in to. Gli elenchi assenti o vuoti non cambiano la struttura dell'hash delle richieste solo To; restano validi i limiti di conservazione della chiave e di idoneità indicati sopra.
Metadati
Aggiungi a qualsiasi invio metadata, le tue stringhe associate a chiavi, per ritrovare il messaggio nei tuoi dati: un ordine, un tenant o una campagna. Oblic memorizza i metadati e li restituisce nelle risposte dei messaggi e nei webhook, ma non li interpreta per la consegna né li inoltra a destinatari o provider. Non oscura segreti o dati sensibili: controlla i valori inseriti; un nome di chiave consentito non è un filtro di riservatezza.
Un SMS con metadati
{
"to": "+919876543210",
"text": "Your order 1042 has shipped.",
"metadata": { "orderId": "1042", "tenant": "acme" }
}
- Fino a 20 chiavi, ciascuna composta da 1 a 40 lettere e cifre ASCII,
_,.o-, e un valore stringa di massimo 500 caratteri. Un numero otrueviene conservato così come scritto, come stringa"1042"o"true";nullo un oggetto vengono rifiutati con400, senza accodare nulla. - Vengono restituiti in Ottenere un messaggio, in ogni voce di Elencare i messaggi e come
data.metadatain ogni webhook del messaggio:{}se il messaggio è stato inviato senza metadati. - Sono parte del messaggio: lo stesso
Idempotency-Keycon metadati diversi è un messaggio diverso e produce409 IDEMPOTENCY_CONFLICT.
Elencare i messaggi
I messaggi inviati tramite API, dal più recente, con una voce per destinatario: un'email a tre indirizzi genera tre voci con lo stesso id.
- Nome
channel- Tipo
- string
- Descrizione
email,smsoppurewhatsapp; ripeti il parametro per selezionarne più di uno.
- Nome
status- Tipo
- string
- Descrizione
queued,sent,delivered,read,bounced,skippedoppurefailed; ripeti il parametro per selezionarne più di uno.
- Nome
since- Tipo
- string
- Descrizione
L'istante iniziale della richiesta, incluso, in ISO 8601 con
Zo un offset UTC esplicito, ad esempio2026-10-01T00:00:00Z. Un'ora locale senza offset non identifica un istante.
- Nome
until- Tipo
- string
- Descrizione
L'istante finale della richiesta, escluso, anch'esso con
Zo un offset UTC esplicito.
- Nome
limit- Tipo
- integer
- Descrizione
Il numero di risultati, da 1 a 100; 25 per impostazione predefinita.
- Nome
cursor- Tipo
- string
- Descrizione
Il
nextdell'ultima pagina, per leggere la successiva. Consulta Paginazione.
Le email saltate questa settimana
curl -G https://api.oblic.app/external/v1/messages \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d channel=email \
-d status=skipped \
-d since=2026-10-19T00:00:00Z
Risposta
{
"status": "success",
"data": {
"messages": [
{
"id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60",
"channel": "email",
"to": "ravi@example.org",
"status": "skipped",
"reason": "unsubscribed",
"requestedAt": "2026-10-20T08:15:02.120Z",
"sentAt": null,
"deliveredAt": null,
"readAt": null,
"failedAt": null,
"openedAt": null,
"clickedAt": null,
"metadata": { "orderId": "1042" }
}
],
"next": null
},
"errors": null
}
statususa lo stesso insieme per ogni canale:queued(non ancora inviato),sent(accettato dal provider),delivered,read,bounced,skipped(non inviato, ad esempio a un indirizzo disiscritto o soppresso) efailed.reasonindica il motivo, ad esempiounsubscribedosuppressedper un destinatario saltato.toè l'indirizzo email, il numero SMS con+91oppure le cifre del numero WhatsApp senza+.- Gli orari indicano quando si è verificato ogni evento oppure
null;openedAteclickedAtriguardano le email. metadatacontiene ciò che è stato associato al messaggio all'invio oppure{}.
Ottenere un messaggio
Un messaggio e il suo esito, tramite l'identificativo restituito all'invio. Un SMS e un messaggio WhatsApp hanno risposte di forma simile, rispettivamente con segments e readAt; un'email ha una forma propria con una voce per ogni destinatario, man mano che arrivano gli eventi.
Un messaggio SMS
{
"status": "success",
"data": {
"id": "msg_9a1b2c3d4e5f60718293a4b5c6d7e8f9",
"channel": "sms",
"status": "delivered",
"segments": 1,
"sentAt": "2026-10-20T08:15:03.410Z",
"deliveredAt": "2026-10-20T08:15:06.902Z",
"failedAt": null,
"failureCode": null,
"metadata": { "orderId": "1042" }
},
"errors": null
}
Un'email
{
"status": "success",
"data": {
"id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60",
"status": "sent",
"recipients": [
{
"email": "asha@example.org",
"deliveredAt": "2026-10-20T08:16:11Z",
"openedAt": "2026-10-20T09:02:40Z",
"bouncedAt": null,
"complainedAt": null,
"delayedAt": null
}
],
"metadata": {}
},
"errors": null
}
- Lo
statusdi un SMS èqueued,sent,delivered,undeliveredoppurefailed. - Quello di un messaggio WhatsApp è
queued,sent,delivered,readoppurefailed, conreadAt. Il suofailureCodeè quello di Meta, ad esempiometa:131026. - Quello di un'email è
queuedfino all'invio, poisent,partially_suppressedquando alcuni destinatari sono saltati,suppressedquando lo sono tutti oppurefailedquando l'invio non riesce. Gli orari di ciascun destinatario derivano dagli eventi del provider email, quindirecipientsè vuoto fino al primo evento. metadatacontiene ciò che è stato associato all'invio oppure{}: consulta Metadati.
Un messaggio assente o non appartenente all'account produce 404 MESSAGE_NOT_FOUND. Un'email mai inviata risulta non trovata qui dopo 24 ore; continua però a comparire nell'elenco.
Riepilogo del rapporto
L'esito dei messaggi richiesti in un periodo, conteggiati per canale e stato, con il numero di email aperte, cliccate o segnalate come spam.
- Nome
from- Tipo
- string
- Descrizione
L'inizio del periodo, incluso, in ISO 8601 con
Zo un offset UTC esplicito; per impostazione predefinita, 30 giorni prima dito.
- Nome
to- Tipo
- string
- Descrizione
La fine del periodo, esclusa, anch'essa con
Zo un offset UTC esplicito; per impostazione predefinita, l'istante attuale. Deve essere successiva afrome distare al massimo 92 giorni.
Risposta
{
"status": "success",
"data": {
"from": "2026-09-24T00:00:00Z",
"to": "2026-10-24T00:00:00Z",
"all": {
"messages": 1250,
"statuses": { "queued": 4, "sent": 96, "delivered": 1075, "read": 30, "bounced": 12, "skipped": 18, "failed": 15 },
"opened": 410,
"clicked": 96,
"complained": 1
},
"channels": {
"email": { "messages": 800, "statuses": { "queued": 2, "sent": 40, "delivered": 728, "read": 0, "bounced": 12, "skipped": 18, "failed": 0 }, "opened": 410, "clicked": 96, "complained": 1 },
"sms": { "messages": 300, "statuses": { "queued": 1, "sent": 36, "delivered": 253, "read": 0, "bounced": 0, "skipped": 0, "failed": 10 }, "opened": 0, "clicked": 0, "complained": 0 },
"whatsapp": { "messages": 150, "statuses": { "queued": 1, "sent": 20, "delivered": 94, "read": 30, "bounced": 0, "skipped": 0, "failed": 5 }, "opened": 0, "clicked": 0, "complained": 0 }
}
},
"errors": null
}
Sono sempre presenti tutti i canali e tutti gli stati, conteggiati con i termini dell'elenco. from uguale o successivo a to, oppure una distanza superiore a 92 giorni, produce 400 INVALID_PERIOD.