Casi d’uso comuni
- Password Reset
- Order Confirmation
- Welcome Email
- Account Deletion
- Purchase Receipt
- Shipping Notifications
- Account Verification
- Payment Confirmations
Funzionalità principali
Gestione automatica dei contatti
- L’oggetto
contactdella richiesta crea il contatto o ne aggiorna i campi prima dell’invio, così le sue informazioni restano aggiornate. - I dati del template (
data) non vengono salvati sul contatto. Le loro chiavi diventano variabili di primo livello del template, e il profilo salvato del contatto è disponibile sottocontact.
Per aggiornare il contatto in questo modo serve il permesso di scrittura sui Contatti. Senza di esso, un invio si limita a creare un contatto mancante a partire dal suo indirizzo email e non modifica mai un contatto esistente (vedi Permessi).
Arricchimento dei dati del template
Quando invii un’email transazionale, Notifuse:
- Crea o aggiorna il contatto, poi lo cerca per indirizzo email nel tuo workspace
- Mette le chiavi di
dataal primo livello delle variabili del template, e il profilo salvato del contatto sottocontact - Genera il template con le informazioni complete del contatto
- Invia l’email personalizzata
Esempio: se la tua API invia "data": {"order_id": "12345"} e il profilo del contatto contiene {"first_name": "John", "last_name": "Doe"}, il template può usare {{ order_id }} e {{ contact.first_name }}.
Deduplicazione con l’ID esterno
- Imposta
external_idper non inviare due volte la stessa notifica: le notifiche con lo stessoexternal_idvengono inviate una sola volta. - Usa i tuoi identificativi univoci (ID degli ordini, ID degli eventi, ecc.).
Esempio: con external_id: "order-12345", la conferma d’ordine viene consegnata una volta sola, anche se il tuo sistema la invia più volte.
Opzioni di consegna dell’email
Ogni invio può impostare:
- Nome Mittente: sostituisce il nome visualizzato predefinito del mittente
- Oggetto: sostituisce l’oggetto del template (supporta Liquid)
- Reply-To: imposta indirizzi di risposta personalizzati
- CC: aggiunge destinatari in copia
- BCC: aggiunge destinatari in copia nascosta
- Allegati: allega file alle email (PDF, immagini, documenti, ecc.)
Tracciamento
Aperture e click seguono le impostazioni del workspace e il consenso al tracciamento del contatto. Un contact nella richiesta può contenere tracking_opens_consent e tracking_clicks_consent, registrati con fonte api a meno che tu non invii tracking_consent_source. Ogni notifica può anche disattivare il tracciamento:
- Nessun tracciamento di aperture o clic, mantieni gli UTM (
tracking_mode: "no_tracking") - Disattivato per questa notifica (
tracking_mode: "disabled"): i link non vengono mai riscritti e non contengono parametri di tracciamento né UTM. Usalo per i link che devono restare come sono, come i link di accesso
Monitoraggio nella console
La pagina Transazionale elenca le tue notifiche con le loro statistiche sugli ultimi 7, 30 o 60 giorni, oggi compreso:
- Totali: email inviate, tasso di consegna con la sua variazione rispetto al periodo precedente, tassi di apertura e di click sulle email tracciate, errori e bounce.
- Una riga per notifica: il suo template, le email inviate, i tassi di consegna, apertura e click, gli errori, il tasso di rimbalzo e l’ultimo invio riuscito. Un tasso di consegna sotto il 97% e un tasso di rimbalzo dal 2% in su sono evidenziati. Puoi cercare per nome o per ID.
- Azioni della riga: inviare una prova, mostrare il comando API e, dal menu, modificare, vedere l’anteprima del template, copiare l’ID, aprirne i messaggi nei log o eliminarla.
Fai clic su una riga per aprire la vista di dettaglio della notifica, che ha un proprio link da condividere. Mostra le stesse statistiche per quella notifica, collegate ai messaggi corrispondenti nei log, più gli invii al giorno, gli ultimi invii (aggiornati ogni 30 secondi), un’anteprima del template, le sue impostazioni di tracciamento e UTM, il mittente predefinito e la chiamata API in cURL, TypeScript e Python. K e J passano alla notifica precedente o successiva.
Con un provider SMTP, i tassi di consegna e di rimbalzo non sono disponibili, perché SMTP non invia eventi di consegna. Le statistiche richiedono il permesso di lettura sulla cronologia dei messaggi.
Endpoint dell’API
Invia un’email transazionale con una richiesta POST:
Richiesta
curl -X POST \
"https://v3.notifuse.com/api/transactional.send" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"workspace_id": "your_workspace",
"notification": {
"id": "password_reset",
"external_id": "pwd-reset-user123-20240101",
"channels": ["email"],
"contact": {
"email": "user@example.com"
},
"data": {
"reset_token": "abc123",
"expiry_time": "2024-01-01T12:00:00Z"
},
"metadata": {
"user_id": "12345",
"trigger": "forgot_password",
"source": "web_app"
},
"email_options": {
"from_name": "Support Team",
"subject": "Reset your password, {{ contact.first_name }}",
"reply_to": "support@yourcompany.com",
"cc": ["admin@yourcompany.com"],
"bcc": ["logs@yourcompany.com"],
"attachments": [
{
"filename": "reset-guide.pdf",
"content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
"content_type": "application/pdf"
}
]
}
}
}'
Parametri
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
workspace_id | string | Sì | L’identificativo del tuo workspace |
notification.id | string | Sì | Identificativo del template dell’email |
notification.external_id | string | No | Identificativo univoco per la deduplicazione |
notification.channels | array | Sì | Deve contenere “email” |
notification.contact | object | Sì | Oggetto contatto con almeno un campo email |
notification.data | object | No | Variabili del template per il contenuto dell’email |
notification.metadata | object | No | Dati di tracciamento (non disponibili nei template) |
notification.email_options | object | No | Configurazione dell’instradamento dell’email |
Opzioni dell’email
| Parametro | Tipo | Descrizione |
|---|---|---|
sender_id | string | Invia da questo mittente dell’integrazione per le email transazionali invece che da quello del template. Un ID sconosciuto viene rifiutato con un 400 prima che il contatto sia creato o aggiornato |
from_name | string | Sostituisce il nome visualizzato predefinito del mittente |
subject | string | Sostituisce l’oggetto del template (supporta Liquid, max 255) |
reply_to | string | Imposta un indirizzo di risposta personalizzato, al posto del reply-to del template |
cc | array | Elenco dei destinatari in copia |
bcc | array | Elenco dei destinatari in copia nascosta |
attachments | array | File allegati (max 20 file, 3MB per file, 10MB in totale) |
Data e metadata a confronto
Variabili del template (data)
L’oggetto data contiene le variabili che i tuoi template email possono usare:
{
"data": {
"order_id": "ORD-12345",
"total": "$99.99",
"discount_code": "WELCOME20"
}
}
Nei template si usano così: {{ order_id }}, {{ total }}, {{ discount_code }}
Dati di tracciamento (metadata)
L’oggetto metadata conserva informazioni per l’analisi e il tracciamento e non è disponibile nei template:
{
"metadata": {
"campaign_id": "welcome-series",
"source": "mobile_app",
"user_segment": "premium"
}
}
Usa i metadata per il tracciamento interno, le analisi e i report.
Allegati delle email
Allega fatture, ricevute, biglietti o altri documenti alle tue email transazionali. Gli allegati vengono deduplicati automaticamente nello storage.
Limiti degli allegati
- Numero massimo di file: 20 allegati per email
- Dimensione del file: 3MB per file
- Dimensione totale: 10MB per email
- Formati supportati: tutti i tipi di file (PDF, PNG, JPEG, DOCX, ecc.)
Parametri degli allegati
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
filename | string | Sì | Nome del file (max 255 caratteri) |
content | string | Sì | Contenuto del file codificato in Base64 |
content_type | string | No | Tipo MIME (per esempio “application/pdf”), rilevato automaticamente se non indicato |
disposition | string | No | “attachment” (predefinito) o “inline” |
content_id | string | No | Content-ID per gli allegati inline, richiamato dal corpo HTML con <img src="cid:...">. Consentito solo quando disposition è “inline”. Se omesso, vale il nome del file. |
Esempio con una fattura PDF
{
"workspace_id": "your_workspace",
"notification": {
"id": "order_confirmation",
"contact": {
"email": "customer@example.com"
},
"data": {
"order_id": "ORD-12345",
"total": "$99.99"
},
"email_options": {
"attachments": [
{
"filename": "invoice-12345.pdf",
"content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
"content_type": "application/pdf",
"disposition": "attachment"
}
]
}
}
}
Esempio con più allegati
{
"email_options": {
"attachments": [
{
"filename": "invoice.pdf",
"content": "JVBERi0xLjQKJeLjz9MK...",
"content_type": "application/pdf"
},
{
"filename": "receipt.png",
"content": "iVBORw0KGgoAAAANSUhEU...",
"content_type": "image/png"
},
{
"filename": "terms.docx",
"content": "UEsDBBQABgAIAAAAIQ...",
"content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
}
]
}
}
Immagini inline (Content-ID)
Incorpora nel corpo dell’email immagini diverse per ogni destinatario, come codici QR o grafiche personalizzate, invece di ospitarle a un URL. Imposta disposition a "inline" e dai all’allegato un content_id, poi richiamalo dall’HTML del template con <img src="cid:...">:
{
"email_options": {
"attachments": [
{
"filename": "check-in-qr.png",
"content": "iVBORw0KGgoAAAANSUhEU...",
"content_type": "image/png",
"disposition": "inline",
"content_id": "checkInQr"
}
]
}
}
E nel template dell’email:
<img src="cid:checkInQr" alt="Your check-in QR code" />
Note:
content_idpuò contenere solo lettere, cifre e i caratteri._-@(max 255 caratteri), ed è accettato solo quandodispositionè"inline".- Quando
content_idè omesso, come Content-ID si usa il nome del file, quindi funziona anche<img src="cid:check-in-qr.png">. - Le immagini inline vengono consegnate in una parte MIME
multipart/relatedinsieme al corpo HTML, così i client di posta le mostrano nel corpo e non come allegati da scaricare. - Poiché l’immagine viaggia dentro il corpo del messaggio, i proxy dei link e i servizi di cache delle immagini non la scaricano né la registrano mai, il che è adatto a segreti legati al destinatario come i codici QR.
- Su Mailgun, il
content_iddiventa anche il nome del file della parte consegnata, quindi quando invii tramite Mailgun preferisci uncontent_idcon estensione (per esempiocheckInQr.png).
Casi d’uso comuni
- Conferme d’ordine: allega fatture e ricevute
- Conferme di prenotazione: allega biglietti e itinerari
- Documenti legali: allega contratti e accordi
- Report: allega report di analisi e riepiloghi
- Certificati: allega certificati di completamento e badge
- Biglietti per eventi: incorpora codici QR personali come immagini inline
Bridge SMTP
Notifuse include un server bridge SMTP, così puoi inviare email transazionali da client SMTP standard invece di chiamare l’API HTTP. È utile per:
- Sistemi legacy: integrare applicazioni esistenti che supportano solo SMTP
- Librerie email: usare le librerie email standard in qualsiasi linguaggio di programmazione
- Integrazione con i framework: lavorare con framework che hanno il supporto SMTP integrato
- Migrazione graduale: lasciare i provider email attuali senza modificare il codice dell’applicazione
Come funziona
Il server bridge SMTP accetta email sulla porta 587 (STARTTLS) o 465 (TLS implicito). Il corpo dell’email deve contenere un payload JSON nel formato dell’API transazionale, e ti autentichi con le credenziali API del tuo workspace.
Inviare email tramite SMTP
Autenticazione
- Nome utente: l’email API del tuo workspace (l’email associata alla tua API Key)
- Password: la API Key del tuo workspace
- Sicurezza: STARTTLS (porta 587) o TLS implicito / SMTPS (porta 465), a seconda dell’impostazione
SMTP_BRIDGE_TLS - Server: l’host del bridge SMTP che hai configurato (per esempio
smtp.yourdomain.com)
Formato dell’email
Il corpo dell’email deve essere un payload JSON conforme al formato dell’API transazionale:
{
"workspace_id": "your_workspace",
"notification": {
"id": "password_reset",
"external_id": "unique-id-123",
"channels": ["email"],
"contact": {
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe"
},
"data": {
"reset_token": "abc123",
"expiry_time": "1 hour"
}
}
}
Permessi
Il solo permesso di scrittura su Transazionale basta per inviare, sia tramite l’API sia tramite il bridge SMTP. Una API Key dedicata al solo invio è quindi pratica: concedi a una chiave la scrittura su Transazionale e nient’altro, e potrà inviare email senza leggere né modificare alcun contatto. Vedi Amministratori e API Key.
Una chiave con permessi così ristretti ha due limiti, sul bridge SMTP come sull’API:
- Senza scrittura sui Contatti, un invio crea comunque il contatto del destinatario quando non esiste ancora, ma salva solo il suo indirizzo email. Tutti gli altri campi dell’oggetto
contactvengono scartati, e un contatto esistente non viene mai modificato. - Senza lettura sui Contatti, un invio che imposta
ccobccviene rifiutato. Sul bridge SMTP,ccebccvengono dalle intestazioniCc:eBcc:del messaggio, quindi una credenziale di solo invio che le imposta viene respinta alla consegna del messaggio.
Aggiungi alla chiave la lettura e la scrittura sui Contatti se deve arricchire i profili dei contatti durante l’invio o aggiungere destinatari in copia. Con entrambe, la chiave si comporta come prima.
La scrittura su Transazionale copre tutti i percorsi che inviano posta reale tramite le credenziali del tuo provider: /api/transactional.send, /api/transactional.testTemplate e il bridge SMTP. Il test di un provider email (/api/email.testProvider) è riservato al proprietario del workspace, quindi una API Key non può chiamarlo. Un’email di prova richiede anche la lettura sui Template, e la lettura sulle Liste quando viene inviata per una lista di distribuzione (list_id).
La lettura su Transazionale copre solo le definizioni delle notifiche (elencarle e aprirne una). Non permette a una chiave di inviare.
Integrazione con i template
Struttura dei dati nei template
I tuoi template possono usare sia i dati dell’API sia il profilo del contatto:
<!-- From API data -->
Hello! Your order #{{ order_id }} has been confirmed.
<!-- From contact profile (automatically enriched) -->
Dear {{ contact.first_name }} {{ contact.last_name }},
<!-- Combining both -->
We've sent your order #{{ order_id }} to {{ contact.email }}.
Blocchi condizionali
I blocchi di un template visuale possono essere inviati solo quando vale una condizione su questi dati, per esempio una sezione mostrata solo quando order.total è maggiore di 100. Vedi Blocchi condizionali.
Esempio completo
Richiesta API:
{
"workspace_id": "your_workspace",
"notification": {
"id": "order_confirmation",
"external_id": "order-12345-confirmation",
"contact": {
"email": "sarah@example.com"
},
"data": {
"order_id": "ORD-12345",
"total": "$99.99",
"items": ["Product A", "Product B"]
},
"metadata": {
"campaign_id": "order-confirmations",
"source": "checkout"
}
}
}
Profilo del contatto esistente:
{
"first_name": "Sarah",
"last_name": "Johnson",
"email": "sarah@example.com",
"phone": "+1234567890"
}
Disponibile nel template:
Hi {{ contact.first_name }}!
Your order #{{ order_id }} totaling {{ total }} has been confirmed.
Items:
{% for item in items %}
- {{ item }}
{% endfor %}
We'll send updates to {{ contact.email }}.
Riferimento API
Esempi di deduplicazione
Conferme d’ordine
{
"external_id": "order-12345-confirmation"
}
Reimpostazione della password
{
"external_id": "pwd-reset-user123-20240101"
}
Email di benvenuto
{
"external_id": "welcome-user123"
}
Schemi coerenti per external_id evitano le notifiche duplicate, anche se la tua applicazione invia più richieste.
Per la documentazione completa dell’API e gli altri parametri, vedi il Riferimento API.
