> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://www.notifuse.com/docs/assets/screenshots/transactional_api.png)

## 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](#permissions)).

### 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](https://www.notifuse.com/it/docs/features/email-tracking.md) 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](https://www.notifuse.com/it/docs/features/logs.md) 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

```bash
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:

```json
{
  "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:

```json
{
  "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

```json
{
  "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

```json
{
  "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:...">`:

```json
{
  "email_options": {
    "attachments": [
      {
        "filename": "check-in-qr.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png",
        "disposition": "inline",
        "content_id": "checkInQr"
      }
    ]
  }
}
```

E nel template dell'email:

```html
<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:

```json
{
  "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](https://www.notifuse.com/it/docs/features/admins-api-keys.md).

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:

```liquid
<!-- 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](https://www.notifuse.com/it/docs/features/templates.md#conditional-blocks).

### Esempio completo

**Richiesta API**:

```json
{
  "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**:

```json
{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "sarah@example.com",
  "phone": "+1234567890"
}
```

**Disponibile nel template**:

```liquid
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

```json
{
  "external_id": "order-12345-confirmation"
}
```

### Reimpostazione della password

```json
{
  "external_id": "pwd-reset-user123-20240101"
}
```

### Email di benvenuto

```json
{
  "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](https://www.notifuse.com/docs/api-reference/send-a-transactional-notification.md).
