API-Referenz

Accoda un'email transazionale per l'invio. La categoria è sempre transaction_receipt, determinata esclusivamente lato server — non esiste alcun modo di selezionarla dalla richiesta.

Il corpo del messaggio si specifica in una delle due modalità seguenti, mai entrambe nella stessa richiesta:

• Contenuto diretto: subject e almeno uno tra html_body/ text_body.
• Da template: template_id (creato in console, POST /email-templates, fuori perimetro di questo documento) e variables, una mappa nome → valore sostituita nei segnaposto {{nome}} del template.

Il brand del messaggio

Ogni invio parte sotto un brand — il marchio con cui il destinatario ti riconosce. Su questo endpoint il brand non si dichiara: si ricava dalla chiave API che autentica la richiesta, a cui è stato legato quando l'hai creata in console. Il legame è immutabile: una chiave scrive sempre e solo sotto quel brand, qualunque cosa accada alla configurazione del tuo account nel frattempo.

Se hai più brand, crei una chiave per brand. Questo è anche ciò che limita il danno se una chiave ti sfugge: porta un brand solo.

Il campo brand_id è facoltativo e serve a una cosa sola, proteggerti da uno scambio di chiavi fra due integrazioni: se lo mandi, deve coincidere con il brand della chiave, altrimenti la richiesta è rifiutata con 403 brand_mismatch. Non può scegliere il brand — con una chiave lo scambio di segreti è altrimenti invisibile, perché produrrebbe messaggi validi sotto il marchio sbagliato.

Se autentichi con la sessione cookie della console (per una prova dagli strumenti di sviluppo) il brand va invece dichiarato, ed è obbligatorio: lì non c'è una credenziale che lo porti.

La risposta di successo è identica indipendentemente dal fatto che il destinatario sia effettivamente recapitabile o si trovi in una suppression list per bounce/complaint pregressi (ADR-0017): nessun campo della risposta permette di distinguere i due casi, per non offrire a un chiamante un modo di verificare l'esistenza/validità di un indirizzo email altrui.

Il flag marketing

Per impostazione predefinita questo endpoint invia messaggi transazionali: ricevute, conferme di operazione, notifiche di servizio. Sono inviabili a chiunque, anche a chi non è un tuo contatto e anche a chi si è disiscritto — la loro base giuridica non è il consenso, ed è la ragione per cui chi si disiscrive continua a ricevere gli avvisi di sicurezza del tuo servizio.

Con "marketing": true dichiari che il messaggio è una comunicazione promozionale. La dichiarazione può soltanto TOGLIERE: aggiunge controlli e non ne rimuove nessuno, e non esiste alcun valore di questo campo che qualifichi un messaggio come transazionale — quella qualifica è determinata dal server e non è dichiarabile.

Un messaggio marketing:

• parte solo verso un indirizzo che è un tuo contatto di quel brand e che ha confermato l'iscrizione;
• non parte verso chi ha revocato il consenso presso quel brand;
• porta automaticamente il link di disiscrizione nel corpo e l'header List-Unsubscribe (RFC 8058). Non c'è modo di ometterli;
• si ferma se il canale del tuo brand è sospeso, come una campagna.

Se il destinatario non è eleggibile la risposta è 403 recipient_not_eligible_for_marketing. Un codice solo per due casi diversi — non è un tuo contatto confermato, oppure ha revocato: distinguerli direbbe a chi possiede la chiave se una data persona è tua cliente e se ti ha detto di no. Per raccogliere il consenso usa POST /contacts.

Le due parti del messaggio: HTML e testo

Il destinatario riceve sempre un messaggio a due parti (multipart/alternative, HTML e testo semplice) con entrambe popolate: una parte vuota non viene mai spedita. Se ne fornisci una sola, l'altra viene derivata da quella che hai mandato; se le fornisci entrambe, partono come le hai scritte, senza modifiche. Una parte contenente solo spazi vale come assente.

Questo conta perché in un multipart/alternative una parte vuota non equivale a una parte assente: il client sceglie l'alternativa più ricca, la trova vuota e mostra un messaggio bianco. Mandare una sola delle due parti è quindi un'integrazione legittima e sicura, non un mezzo messaggio.

Vale allo stesso modo per la modalità template_id: un template produce solo HTML, quindi la parte testo è sempre derivata.

Se mandi solo html_body

La parte testo è il tuo HTML ridotto a testo leggibile:

• i link diventano etichetta(url): l'indirizzo compare in chiaro, fra parentesi, subito dopo il testo del link. Nessun link va quindi perso per chi legge la versione testuale — un link di conferma, di disiscrizione o di annullamento deve restare raggiungibile in entrambe le parti, ed è un requisito legale, non una scelta estetica. L'URL è omesso solo quando non aggiunge nulla: ancora interna (#...) o etichetta già identica all'indirizzo;
• le immagini diventano il loro testo alternativo fra parentesi quadre ([Logo]); quelle senza alt spariscono;
• le voci di elenco diventano righe che iniziano con - ;
• paragrafi e titoli restano separati da una riga vuota, righe e celle di tabella da un a capo semplice; <br> resta un a capo singolo;
• <script>, <style> e il <title> non finiscono nel testo.

Esempio — questo html_body:

<p>Ordine #4821 confermato.
<a href="https://negozio.example/ordini/4821">Vedi il dettaglio</a></p>

produce questa parte testo:

Ordine #4821 confermato. Vedi il dettaglio (https://negozio.example/ordini/4821)

Se mandi solo text_body

La parte HTML è il tuo testo avvolto in un layout minimo e neutro: le righe vuote separano i paragrafi, gli a capo singoli restano tali, gli URL riconoscibili diventano cliccabili. Il testo è sempre escapato — non viene interpretato come markup — quindi eventuali < e & arrivano come li hai scritti.

Il layout non aggiunge il marchio mailronix né alcuna riga di piè di pagina: il messaggio parte dal tuo dominio verificato e deve continuare a essere riconoscibile come tuo.

Se vuoi controllo pieno sulle due parti

Mandale entrambe. La derivazione è una rete di sicurezza per chi ne fornisce una sola, non una riscrittura di ciò che fornisci: una parte che hai valorizzato non viene mai toccata.

Ritentare in sicurezza: Idempotency-Key

Un timeout o un errore di rete non ti dice se la richiesta è stata accodata: ritentare senza precauzioni può duplicare l'invio. Manda l'header Idempotency-Key (una stringa a tua scelta, univoca per questo invio — un id d'ordine, per esempio) e un retry con lo stesso header e lo stesso corpo riceve la risposta della prima chiamata, email_log_id incluso, senza accodare una seconda volta.

• Valida per 24 ore dalla prima chiamata; dopo, lo stesso valore può essere riusato per un invio nuovo.
• Legata alla chiave API: solo sull'autenticazione a chiave, mai a sessione. Due chiavi diverse non collidono mai sullo stesso valore, nemmeno dello stesso brand.
• Stesso header, corpo diverso dalla prima chiamata → 422 idempotency_key_body_mismatch. Non è un'ambiguità risolta in silenzio: riusare un nome per una richiesta diversa è un errore da correggere lato tuo, non un'esecuzione alternativa.
• Facoltativo: senza l'header il comportamento è quello di sempre, un retry è un secondo invio.

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Conferma ordine #4821",
  "html_body": "<p>Il tuo ordine #4821 è confermato.</p>"
}

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Conferma ordine #4821",
  "html_body": "<p>Il tuo ordine #4821 è confermato.</p>",
  "brand_id": "3f2b8c1d-9a4e-4c7b-8e5f-1a2b3c4d5e6f"
}

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Conferma ordine #4821",
  "text_body": "Il tuo ordine #4821 è confermato.\n\nDettaglio: https://negozio.example/ordini/4821"
}

{
  "from": "[email protected]",
  "to": "[email protected]",
  "template_id": "5f1d6c2e-3b4a-4f0e-9c1a-2d8e7f6a1b3c",
  "variables": {
    "nome_cliente": "Maria",
    "numero_ordine": "4821"
  }
}

{
  "status": "queued",
  "email_log_id": "9c4e2f1a-7d3b-4a5e-8f6c-1b2a3d4e5f6a"
}

{
  "error": {
    "code": "invalid_request",
    "message": "from e to sono obbligatori."
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "brand_id è obbligatorio: indica il brand da cui parte questo invio."
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "from non è un indirizzo email valido."
  }
}

{
  "error": {
    "code": "invalid_from_name",
    "message": "from_name non è valido: da 1 a 78 caratteri, senza «@», «<», «>», virgolette, a-capo o indirizzi web."
  }
}

{
  "error": {
    "code": "invalid_reply_to",
    "message": "reply_to non è un indirizzo email valido: serve un solo indirizzo, senza nome e senza spazi."
  }
}

{
  "error": {
    "code": "invalid_language",
    "message": "language deve essere una tra it, en, es, de, fr."
  }
}

{
  "error": {
    "code": "too_many_attachments",
    "message": "Troppi allegati: al massimo 5 per messaggio."
  }
}

{
  "error": {
    "code": "invalid_attachment",
    "message": "Allegato non valido: servono filename, content_type e content in base64 standard, non vuoti."
  }
}

{
  "error": {
    "code": "attachment_type_not_allowed",
    "message": "Tipo di allegato non ammesso. Sono ammessi application/pdf, image/png, image/jpeg, image/gif, text/plain, text/csv e text/calendar; il contenuto e l'estensione del nome devono corrispondere al tipo dichiarato."
  }
}

{
  "error": {
    "code": "attachments_not_allowed_for_marketing",
    "message": "Un messaggio marketing non può avere allegati: gli allegati sono ammessi solo sui messaggi transazionali."
  }
}

{
  "error": {
    "code": "missing_template_variable",
    "message": "Il template referenzia una variabile non fornita."
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Autenticazione richiesta."
  }
}

{
  "error": {
    "code": "from_address_not_of_brand",
    "message": "Il dominio del mittente non è quello del brand da cui parte questo invio: un brand invia dal proprio dominio (o da un suo sottodominio verificato). Vedi il dominio del brand su GET /brands."
  }
}

{
  "error": {
    "code": "domain_not_verified",
    "message": "Il dominio del mittente non è verificato per questo tenant."
  }
}

{
  "error": {
    "code": "tenant_suspended",
    "message": "Il tenant è sospeso."
  }
}

{
  "error": {
    "code": "free_daily_recipients_exceeded",
    "message": "Limite giornaliero di destinatari unici del piano Free raggiunto."
  }
}

{
  "error": {
    "code": "plan_limit_exceeded",
    "message": "Limite mensile del piano superato."
  }
}

{
  "error": {
    "code": "reply_to_not_allowed",
    "message": "Questo brand non consente di indicare un reply_to nella richiesta: attivalo nelle impostazioni del brand in console."
  }
}

{
  "error": {
    "code": "brand_mismatch",
    "message": "Il brand dichiarato non è quello a cui questa chiave è legata: la chiave scrive sotto un brand solo, e il campo brand_id può solo confermarlo."
  }
}

{
  "error": {
    "code": "template_not_found",
    "message": "Template non trovato."
  }
}

{
  "error": {
    "code": "brand_archived",
    "message": "Il brand è archiviato: riattivalo prima di usarlo."
  }
}

{
  "error": {
    "code": "brand_sender_not_configured",
    "message": "Questo brand non ha ancora un indirizzo mittente: impostane uno, su un dominio verificato, prima di inviare in suo nome."
  }
}

{
  "error": {
    "code": "attachments_too_large",
    "message": "Gli allegati superano 7 MB in totale (dimensione dopo la decodifica base64)."
  }
}

{
  "error": {
    "code": "payload_too_large",
    "message": "Corpo della richiesta troppo grande."
  }
}

{
  "error": {
    "code": "idempotency_key_body_mismatch",
    "message": "Questa Idempotency-Key è già stata usata con un corpo diverso."
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Troppe richieste, riprova più tardi."
  }
}

{
  "error": {
    "code": "server_busy",
    "message": "Troppe richieste con corpo grande in corso: riprova fra qualche secondo."
  }
}

{
  "error": {
    "code": "attachments_backlog",
    "message": "Hai troppi allegati in attesa di invio: riprova fra qualche secondo, quando quelli già accodati saranno partiti."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Errore interno."
  }
}

{
  "error": {
    "code": "auth_unavailable",
    "message": "Verifica della chiave non disponibile."
  }
}

Restituisce lo stato dell'invio identificato da email_log_id — il valore che POST /email/send ti ha restituito. Non esiste un modo di scoprire l'id di un invio che non è il tuo: un id inesistente o appartenente a un altro brand riceve lo stesso 404, senza distinzione.

Gli stati, e perché sono meno di quelli interni

undelivered copre sia un bounce reale sia un indirizzo già soppresso per bounce/complaint pregressi (ADR-0017), e la distinzione è deliberata, non un'approssimazione provvisoria. Un indirizzo soppresso non genera alcun invio reale: se questo endpoint lo segnalasse come caso distinto, chiunque potrebbe mandare POST /email/send a un indirizzo qualsiasi e usare questo endpoint per scoprire gratis se è già soppresso per il tuo brand — lo stesso oracolo che POST /email/send chiude restituendo sempre lo stesso 202, spostato di una chiamata. Con undelivered unico sai comunque che il messaggio non è arrivato — la domanda a cui questo endpoint risponde.

Il valore da solo non basta: anche il momento in cui questo endpoint smette di rispondere queued è parte del presidio. Un indirizzo soppresso si risolve nell'istante stesso dell'invio; un bounce vero richiede il giro reale (coda, invio, notifica del provider) e non può concludersi altrettanto in fretta. Per questo una richiesta fatta a meno di qualche secondo dall'invio risponde sempre queued, anche se l'esito è già determinato: senza questo, la rapidità della risposta rivelerebbe la stessa informazione che il valore unico undelivered nasconde.

{
  "email_log_id": "9c4e2f1a-7d3b-4a5e-8f6c-1b2a3d4e5f6a",
  "status": "sent"
}

Crea un contatto non confermato sotto il brand della chiave e gli invia la richiesta di conferma dell'iscrizione.

Il consenso non si dichiara

Questo endpoint non consente in alcun modo di creare un contatto già confermato né di dichiarare un consenso raccolto altrove. Il contatto nasce in attesa, la richiesta di conferma parte da noi, e ciò che vale come consenso è il click del destinatario. È lo stesso identico flusso della console: cambia come autentichi la chiamata, non la natura dell'atto.

Finché il contatto non conferma non riceve nessun messaggio marketing — e un POST /email/send con "marketing": true verso quell'indirizzo è rifiutato.

La risposta non dice cosa c'era prima

La risposta è la stessa — 204, corpo vuoto — che l'indirizzo sia nuovo, che fosse già un tuo contatto, o che avesse revocato il consenso presso questo brand. Non è una semplificazione: tre risposte distinte permetterebbero a chi possiede la chiave di verificare, un indirizzo per volta, se una data persona è tua cliente e se ti ha detto di no.

Ne segue che questa risposta non restituisce alcun identificativo, e che gli altri endpoint su questa superficie indirizzano un contatto per (brand, email).

Se l'indirizzo aveva revocato presso questo brand, il contatto viene creato inerte: nessuna richiesta di conferma parte, e nessuna operazione tua può riattivarlo — solo una nuova iscrizione della persona stessa.

Revoca il consenso di un contatto del brand della chiave. È l'endpoint da chiamare quando una persona toglie il consenso nella tua applicazione.

Chiamalo tu, e non usare la cancellazione al suo posto. Una cancellazione non registra alcuna revoca: la sincronizzazione successiva ricrea il contatto, e gli parte una nuova richiesta di conferma — cioè scriviamo a una persona che si era appena disiscritta.

La revoca non si annulla

Non esiste alcun modo, per te o per noi, di annullare una revoca: il contatto potrà tornare a ricevere comunicazioni solo con una nuova iscrizione fatta da lui. Per questa ragione il limite di richieste su questa operazione non ti rallenta e basta: superarlo disabilita la chiave, e riattivarla richiede una persona che entri in console.

La risposta è la stessa che l'indirizzo fosse un contatto o no.

Puoi chiamarlo prima di averci mandato il contatto

Se l'indirizzo non è ancora un tuo contatto, la revoca viene registrata lo stesso. Da quel momento quell'indirizzo non riceve nulla per quel brand: se in seguito lo crei con POST /contacts, il contatto nasce inerte, nessuna richiesta di conferma parte, e nessuna campagna lo raggiunge.

È il caso della persona che toglie il consenso nella tua applicazione prima che tu ci abbia mai sincronizzato quel contatto — l'ordine è il tuo, non il nostro.

⚠️ Non usarlo su indirizzi che non hai motivo di negare. La riga scritta è definitiva anche per te: non si cancella, non si corregge, e non esiste un'operazione inversa. Un indirizzo revocato per errore torna a ricevere comunicazioni solo con una nuova iscrizione fatta dalla persona.

Ogni revoca porta il nome della chiave che l'ha scritta

Le revoche registrate da questo endpoint sono elencate in console, con la data, l'indirizzo e il prefisso della chiave che le ha registrate — anche quelle su indirizzi che non erano contatti.

Non è un dettaglio di interfaccia ed è bene che tu lo sappia scrivendo l'integrazione: se una chiave compromessa comincia a negare indirizzi, chi amministra l'account lo vede e sa quale chiave disabilitare. Le revoche registrate prima dell'introduzione di questa tracciatura restano senza attribuzione: non è stata indovinata a posteriori.

Elimina il contatto del brand della chiave.

Non è il modo di dire «si è disiscritto». Per quello esiste POST /contacts/revoke, e la differenza è sostanziale: una cancellazione rimuove il dato ma non registra alcuna revoca, quindi non impedisce che un caricamento successivo ricrei il contatto e faccia ripartire la richiesta di conferma.

Una revoca già registrata, invece, sopravvive alla cancellazione: se hai revocato prima di cancellare, ricreare quel contatto lo fa nascere inerte e nessun messaggio parte. È la ragione per cui contacts:delete non è concedibile senza contacts:unsubscribe.

POST e non DELETE perché il contatto si indirizza per (brand, email) e l'indirizzo viaggia nel corpo: metterlo in query string lo scriverebbe nei log di ogni intermediario.

Un POST è verbo di metodo, non un'operazione idempotente diversa: chiamarlo due volte sullo stesso indirizzo produce lo stesso esito.

Restituisce, in ordine cronologico di revoca, le disiscrizioni registrate per il brand a cui questa chiave è legata — tutte, non solo quelle che hai registrato tu: il click sul link di disiscrizione di una nostra email, l'azione di chi amministra l'account in console, e le tue chiamate a POST /contacts/revoke.

È l'endpoint da usare per riconciliare: sapere delle revoche avvenute fuori dalla tua integrazione, e smettere di scrivere a chi ha detto di no.

Il cursore

Il campo next_cursor è una stringa opaca: non interpretarla, non costruirla, non derivarne una data. Conservala e rimandala in since alla richiesta successiva.

Il cursore è stabile: due revoche registrate nello stesso istante non fanno saltare né ripetere una riga. È la ragione per cui non è una data — con una data, due disiscrizioni scritte nella stessa transazione (succede: un'importazione, una cancellazione a cascata) starebbero sullo stesso valore, e la seconda non ti arriverebbe mai.

Il cursore è legato alla chiave che lo ha ricevuto: presentato da una chiave di un altro brand riceve 400 invalid_cursor. Non è un token di autorizzazione e non ti dà accesso a nulla — è una posizione dentro un insieme che sei già autorizzato a leggere per intero.

Come si sincronizza

1. prima volta: chiama senza since e scorri finché has_more è false;
2. conserva l'ultimo next_cursor;
3. dalla volta dopo: chiama con since=<cursore conservato>.

La condizione di fine è has_more == false, non next_cursor == null. Questa non è una paginazione ma una coda che si segue: while next_cursor != null — l'abitudine che si porta dalla paginazione classica — qui non termina mai.

A coda finita next_cursor non è nullo: è la tua posizione, e resta valida. Una chiamata che non trova nulla di nuovo restituisce items vuoto, has_more a false e lo stesso cursore che le hai dato — non devi ricominciare da capo.

next_cursor è nullo in un caso solo: la prima chiamata su un brand che non ha ancora alcuna revoca — cioè pagina vuota e nessun since in ingresso. Non c'è ancora una posizione da ricordare, e la chiamata successiva va fatta di nuovo senza since. Non esiste il caso «avevo un cursore e ricevo null»: con un since valido in ingresso il cursore torna sempre valorizzato, anche a pagina vuota.

Il campo revoked_at

È l'istante in cui la persona ha revocato, non quello in cui tu lo leggi né quello in cui noi lo abbiamo registrato una seconda volta. Una revoca ripetuta sullo stesso indirizzo non sposta questa data: la riga conserva l'istante e l'origine della prima — che è anche il motivo per cui richiamare POST /contacts/revoke su un indirizzo già revocato non rompe niente.

Il campo origin

Ti dice chi ha agito, non quale credenziale:

api_key non dice quale chiave: quante integrazioni hai e come si chiamano non è un'informazione che una di esse debba apprendere. Se ti serve, è in console.

Cosa questo endpoint non fa

Non ti dice quante revoche esistono: non c'è un totale, e non c'è modo di ottenerlo. Scorri, oppure no.

Non ti dice se un indirizzo revocato sia anche un tuo contatto attuale. Le due cose sono indipendenti: la memoria di una revoca sopravvive alla cancellazione del contatto — è ciò che impedisce a un ciclo «cancella e ricrea» di far tornare inviabile chi si era disiscritto — quindi in questa coda puoi trovare indirizzi che nel tuo elenco contatti non esistono più. È corretto che sia così, e vanno trattati come tutti gli altri: a quegli indirizzi non si scrive.

Non attraversa i brand: vedi le revoche del brand di questa chiave, e nient'altro. Con più brand servono più chiavi.

mailronix invia questa richiesta al tuo server, all'indirizzo HTTPS registrato in console. Il tuo ricevitore la implementa; non è un endpoint di mailronix.

Rispondi in fretta, con un 2xx

Qualunque risposta 2xx conferma la consegna. Tutto il resto è un fallimento e provoca un nuovo tentativo: 3xx compresi — i redirect non vengono seguiti. Il tempo massimo di un tentativo è 10 secondi. Del corpo della risposta leggiamo al più 1 KB e non lo conserviamo oltre un estratto troncato. Accetta l'evento, scrivilo in una coda tua e rispondi; l'elaborazione vera falla dopo.

Verifica la firma PRIMA di fidarti del corpo

Ogni richiesta porta l'intestazione Mailronix-Signature:

Mailronix-Signature: t=1761141791,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

1. Leggi t (secondi Unix) e tutti i valori v1.
2. Calcola HMAC-SHA256(segreto, t + "." + corpo_grezzo), in esadecimale minuscolo. Usa il corpo grezzo, byte per byte, così come è arrivato: non rileggere e riserializzare il JSON.
3. Confronta con ciascun v1 a tempo costante. Basta che uno corrisponda.
4. Rifiuta se t dista più di 5 minuti dall'ora del tuo server: protegge dai replay. t è l'istante di questo tentativo, non della creazione dell'evento, quindi un nuovo tentativo dopo ore passa comunque la finestra.

Il segreto (whsec_…) ti viene mostrato una sola volta, alla creazione dell'endpoint o alla rotazione. Dopo una rotazione senza revoca immediata, per 24 ore ogni richiesta porta due valori v1, quello del segreto nuovo e quello del precedente: aggiorna il tuo ricevitore senza interruzioni, verificando contro entrambi i segreti finché non hai finito.

import hmac, hashlib, time

def verifica(intestazione, corpo: bytes, segreto: bytes, tolleranza=300):
    parti = [p.strip().split("=", 1) for p in intestazione.split(",")]
    t = next(v for k, v in parti if k == "t")
    firme = [v for k, v in parti if k == "v1"]
    if abs(time.time() - int(t)) > tolleranza:
        return False
    atteso = hmac.new(segreto, t.encode() + b"." + corpo, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(atteso, f) for f in firme)

Idempotenza e ordine

Ogni evento ha un id stabile (evt_…) e lo ritrovi nell'intestazione Mailronix-Event-Id. Lo stesso evento può arrivarti più volte — dopo un tentativo andato a vuoto, un rinvio dalla console, un ripristino dopo un'interruzione nostra — quindi il tuo ricevitore deve essere idempotente su id. L'ordine non è garantito: usa created_at per ordinare.

Tentativi

Un tentativo fallito viene ripetuto dopo 10 secondi, 1 minuto, 5 minuti, 30 minuti, 2 ore, 6 ore, 12 ore, 24 ore e 48 ore: dieci tentativi in tutto, in circa quattro giorni. Poi la consegna risulta fallita e puoi rinviarla dalla console. Se una consegna esaurisce i tentativi e l'endpoint non ne ha avuta nessuna riuscita nelle ultime 72 ore, l'endpoint viene disattivato e il titolare dell'account riceve un avviso; si riattiva dalla console. Gli eventi si conservano 30 giorni.

Che cosa non facciamo

Non seguiamo redirect, non usiamo proxy, non consegniamo a indirizzi che si risolvono verso reti private, loopback o link-local (verifica rifatta a ogni tentativo, non solo alla registrazione) e non inviamo mai il corpo dell'email.

{
  "id": "evt_3f1a9c2e7b6d4e8f9a0b1c2d3e4f5a6b",
  "type": "email.bounced",
  "api_version": "2026-10-22",
  "created_at": "2026-10-22T14:03:11Z",
  "brand_id": "6f1d2c0e-8b1a-4c53-9a77-0d6a7b3a2c11",
  "data": {
    "email_log_id": "0b7c1e52-3f0a-4d3e-8a8e-5b1f2c9d4e60",
    "recipient": "[email protected]",
    "category": "transactional",
    "bounce_type": "permanent"
  }
}

{
  "id": "evt_9c4e2a1b7d3f4a6e8b0c1d2e3f4a5b6c",
  "type": "contact.unsubscribed",
  "api_version": "2026-10-22",
  "created_at": "2026-10-22T14:07:42Z",
  "brand_id": "6f1d2c0e-8b1a-4c53-9a77-0d6a7b3a2c11",
  "data": {
    "contact_id": null,
    "email": "[email protected]"
  }
}