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.

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
}

POST/external/v1/messages/email

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 cc o bcc fornisce destinatari. Inserisci da 1 a 50 voci di indirizzo complessive tra to, cc e bcc; ogni singolo elenco può essere assente o vuoto. Un totale vuoto viene rifiutato su to.

  • 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 aggiunge via Oblic quando 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. Con templateId, se non lo specifichi viene usato l'oggetto del modello.

  • Nome
    html
    Tipo
    string
    Descrizione

    L'HTML dell'email, inviato così come fornito. Specifica html oppure templateId, 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 da variables così 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.

RifiutocdQuando
400il campo, ad esempio TO[0]Un campo è mancante o non valido; un insieme combinato di destinatari vuoto o troppo grande viene rifiutato su to
400INVALID_REQUESTNon viene fornito nessuno tra html e templateId, oppure vengono forniti entrambi; sono presenti variables senza modello oppure manca l'oggetto
400INVALID_VARIABLESUn segnaposto non ha valore, un nome compare due volte con maiuscole diverse oppure l'oggetto compilato è troppo lungo
400INVALID FILEUn allegato è troppo grande o di un tipo non accettato
403EMAIL_SUSPENDEDLe email dell'account sono sospese per mancati recapiti o segnalazioni di spam, fino alla riattivazione da parte dell'assistenza Oblic
413MESSAGE_TOO_LARGEL'email è troppo grande per essere accodata
422UNVERIFIED_SENDERfrom non appartiene a un'identità verificata; il messaggio elenca quelle verificate
422TEMPLATE_NOT_FOUNDNon esiste un modello email con quell'identificativo
422TEMPLATE_HAS_MENTIONSIl modello contiene menzioni della dashboard, come @unsubscribe, compilate soltanto da campagne e automazioni
429RATE_LIMITEDSuperamento 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
429QUOTA_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.


POST/external/v1/messages/sms

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: +91 e 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) oppure promotional. Un messaggio promozionale corrisponde soltanto a modelli promozionali; gli altri soltanto a modelli non promozionali.

  • Nome
    unicode
    Tipo
    boolean
    Descrizione

    true per 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.

RifiutocdQuando
400INVALID_NUMBERto non è un numero di cellulare indiano
400INVALID_REQUESTNon viene fornito nessuno tra text e templateId, oppure vengono forniti entrambi
400INVALID_VARIABLESLe variabili non corrispondono al modello
402INSUFFICIENT_BALANCEL'SMS è promozionale e il portafoglio che paga per l'account è vuoto
422TEMPLATE_NOT_REGISTEREDIl testo o il templateId non corrisponde a nessun modello consentito per l'account oppure a nessuno sotto senderId
422SENDER_NOT_ALLOWEDsenderId non è l'intestazione di alcun modello consentito per l'account
422MESSAGE_TYPE_NOT_ENABLEDIl tipo del modello non viene inviato da Oblic: i tipi inviati sono i messageTypes dell'account, per impostazione predefinita soltanto service_implicit
422URL_NOT_WHITELISTEDUna variabile contiene un collegamento il cui dominio non è nella lista consentita DLT
422OUTSIDE_PROMOTIONAL_HOURSUn SMS promozionale fuori dall'intervallo 10:00–21:00, ora dell'India; Retry-After indica quando riprovare
429RATE_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
429QUOTA_EXCEEDEDÈ superato il numero di segmenti mensili dell'account (10,000 per impostazione predefinita); Retry-After indica quando riprovare
503SMS_UNAVAILABLEAl 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.


POST/external/v1/messages/whatsapp

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 template oppure text, mai entrambi.

  • Nome
    language
    Tipo
    string
    Descrizione

    La lingua del modello, ad esempio en o hi; en per 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.

RifiutocdQuando
400INVALID_REQUESTNon viene fornito nessuno tra template e text, oppure vengono forniti entrambi, o si usa headerVariables o headerMediaUrl con text
402INSUFFICIENT_BALANCEIl modello è di marketing e il portafoglio che paga per l'account è vuoto
422INVALID_NUMBERto non è un numero in formato internazionale
422WHATSAPP_NOT_CONNECTEDL'account non ha un numero WhatsApp collegato
422TEMPLATE_NOT_FOUNDL'account non ha un modello con quel nome e quella lingua
422TEMPLATE_NOT_APPROVEDMeta non ha approvato il modello
422INVALID_VARIABLESIl 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 è
422MEDIA_REQUIREDL'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
422TEMPLATE_NOT_SENDABLEIl modello richiede elementi non inviabili dall'API: un'intestazione con posizione, un pulsante con valore proprio o una variabile denominata
422RECIPIENT_OPTED_OUTUn modello di marketing è destinato a un numero che ha revocato il consenso
422OUTSIDE_SESSION_WINDOWUna 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 202 con l'identificativo del primo messaggio, senza inviarlo due volte.
  • La stessa chiave con un messaggio diverso, compresi i suoi metadata, viene rifiutata con 409 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 o true viene conservato così come scritto, come stringa "1042" o "true"; null o un oggetto vengono rifiutati con 400, senza accodare nulla.
  • Vengono restituiti in Ottenere un messaggio, in ogni voce di Elencare i messaggi e come data.metadata in ogni webhook del messaggio: {} se il messaggio è stato inviato senza metadati.
  • Sono parte del messaggio: lo stesso Idempotency-Key con metadati diversi è un messaggio diverso e produce 409 IDEMPOTENCY_CONFLICT.

GET/external/v1/messages

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, sms oppure whatsapp; ripeti il parametro per selezionarne più di uno.

  • Nome
    status
    Tipo
    string
    Descrizione

    queued, sent, delivered, read, bounced, skipped oppure failed; ripeti il parametro per selezionarne più di uno.

  • Nome
    since
    Tipo
    string
    Descrizione

    L'istante iniziale della richiesta, incluso, in ISO 8601 con Z o un offset UTC esplicito, ad esempio 2026-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 Z o 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 next dell'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
}
  • status usa 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) e failed. reason indica il motivo, ad esempio unsubscribed o suppressed per un destinatario saltato.
  • to è l'indirizzo email, il numero SMS con +91 oppure le cifre del numero WhatsApp senza +.
  • Gli orari indicano quando si è verificato ogni evento oppure null; openedAt e clickedAt riguardano le email.
  • metadata contiene ciò che è stato associato al messaggio all'invio oppure {}.

GET/external/v1/messages/{messageId}

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 status di un SMS è queued, sent, delivered, undelivered oppure failed.
  • Quello di un messaggio WhatsApp è queued, sent, delivered, read oppure failed, con readAt. Il suo failureCode è quello di Meta, ad esempio meta:131026.
  • Quello di un'email è queued fino all'invio, poi sent, partially_suppressed quando alcuni destinatari sono saltati, suppressed quando lo sono tutti oppure failed quando l'invio non riesce. Gli orari di ciascun destinatario derivano dagli eventi del provider email, quindi recipients è vuoto fino al primo evento.
  • metadata contiene 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.


GET/external/v1/reports/summary

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 Z o un offset UTC esplicito; per impostazione predefinita, 30 giorni prima di to.

  • Nome
    to
    Tipo
    string
    Descrizione

    La fine del periodo, esclusa, anch'essa con Z o un offset UTC esplicito; per impostazione predefinita, l'istante attuale. Deve essere successiva a from e 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.

Questa pagina è stata utile?