Vai al contenuto

Funzionalità

API transazionale

Invia dalla tua applicazione email legate a un evento. A differenza dei broadcast, le email transazionali partono verso un contatto alla volta, in tempo reale, e Notifuse crea o aggiorna il contatto durante l'invio. Usale per le notifiche attivate dai tuoi utenti e per i flussi automatici.

Elenco delle notifiche transazionali nella console

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 contact della 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 sotto contact.

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:

  1. Crea o aggiorna il contatto, poi lo cerca per indirizzo email nel tuo workspace
  2. Mette le chiavi di data al primo livello delle variabili del template, e il profilo salvato del contatto sotto contact
  3. Genera il template con le informazioni complete del contatto
  4. 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_id per non inviare due volte la stessa notifica: le notifiche con lo stesso external_id vengono 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

ParametroTipoObbligatorioDescrizione
workspace_idstringSìL’identificativo del tuo workspace
notification.idstringSìIdentificativo del template dell’email
notification.external_idstringNoIdentificativo univoco per la deduplicazione
notification.channelsarraySìDeve contenere “email”
notification.contactobjectSìOggetto contatto con almeno un campo email
notification.dataobjectNoVariabili del template per il contenuto dell’email
notification.metadataobjectNoDati di tracciamento (non disponibili nei template)
notification.email_optionsobjectNoConfigurazione dell’instradamento dell’email

Opzioni dell’email

ParametroTipoDescrizione
sender_idstringInvia 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_namestringSostituisce il nome visualizzato predefinito del mittente
subjectstringSostituisce l’oggetto del template (supporta Liquid, max 255)
reply_tostringImposta un indirizzo di risposta personalizzato, al posto del reply-to del template
ccarrayElenco dei destinatari in copia
bccarrayElenco dei destinatari in copia nascosta
attachmentsarrayFile 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

ParametroTipoObbligatorioDescrizione
filenamestringSìNome del file (max 255 caratteri)
contentstringSìContenuto del file codificato in Base64
content_typestringNoTipo MIME (per esempio “application/pdf”), rilevato automaticamente se non indicato
dispositionstringNo“attachment” (predefinito) o “inline”
content_idstringNoContent-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_id può contenere solo lettere, cifre e i caratteri . _ - @ (max 255 caratteri), ed è accettato solo quando disposition è "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/related insieme 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_id diventa anche il nome del file della parte consegnata, quindi quando invii tramite Mailgun preferisci un content_id con estensione (per esempio checkInQr.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 contact vengono scartati, e un contatto esistente non viene mai modificato.
  • Senza lettura sui Contatti, un invio che imposta cc o bcc viene rifiutato. Sul bridge SMTP, cc e bcc vengono dalle intestazioni Cc: e Bcc: 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.