> ## 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.

# SMTP

> Configura SMTP come provider email in Notifuse con Basic Auth o OAuth2.

L'integrazione SMTP collega a Notifuse qualsiasi servizio email compatibile con SMTP, con autenticazione tramite password oppure con OAuth2 per Microsoft 365 e Gmail.

## Configurazione

Vai in **Impostazioni** → **Integrazioni**, clicca **Aggiungi integrazione**, poi scegli **SMTP** sotto **Invio email**. Il modulo si apre a tutta pagina.

### Impostazioni di base

| Campo             | Descrizione                                                                                                          | Esempio               |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------- |
| **Nome**          | Nome visualizzato di questa configurazione SMTP                                                                      | `Company SMTP`        |
| **Host**          | Hostname del server SMTP                                                                                             | `smtp.gmail.com`      |
| **Porta**         | Numero di porta del server SMTP: 587 per STARTTLS, 465 per TLS dal primo byte, 25 senza crittografia                 | `587`                 |
| **Crittografia**  | L'interruttore **Usa TLS**. Attivo: STARTTLS, o TLS dal primo byte sulla porta 465. Disattivo: testo in chiaro       | `On`                  |
| **Hostname EHLO** | Hostname inviato con il comando SMTP EHLO. Se vuoto, si usa l'host. Utile quando un server rifiuta `EHLO localhost`. | `mail.yourdomain.com` |

### Tipo di autenticazione

Scegli una delle due opzioni in **Metodo**, nel pannello **Autenticazione**:

| Opzione                    | Descrizione                    | Caso d'uso                                            |
| -------------------------- | ------------------------------ | ----------------------------------------------------- |
| **Nome utente e password** | Autenticazione di base         | La maggior parte dei server SMTP, password per le app |
| **OAuth2**                 | Autenticazione basata su token | Microsoft 365, Gmail (obbligatoria dal 2024)          |

---

## Autenticazione di base

Per i server SMTP che accettano una password, o i servizi che supportano le password per le app.

| Campo           | Descrizione                                                                                  | Esempio                |
| --------------- | -------------------------------------------------------------------------------------------- | ---------------------- |
| **Nome utente** | Nome utente per l'autenticazione. Lascialo vuoto per un server che accetta posta senza login | `your-email@gmail.com` |
| **Password**    | Password per l'autenticazione                                                                | `your-app-password`    |

---

## Autenticazione OAuth2

Microsoft 365 e Gmail hanno deprecato l'autenticazione di base, quindi richiedono OAuth2.

### OAuth2 per Microsoft 365

![Microsoft 365](https://www.notifuse.com/docs/assets/microsoft-365-icon.svg)

Microsoft 365 usa il **Client Credentials Flow** per l'autenticazione da server a server.

#### Prerequisiti

- Un account Microsoft 365 Business (non un account personale Outlook.com)
- Accesso amministratore ad Azure AD
- Accesso amministratore a Exchange Online

#### Passo 1: registra un'applicazione Azure AD

1. Vai in [Azure Portal](https://portal.azure.com) → **Azure Active Directory** → **App registrations**
2. Clicca **New registration**
3. Inserisci un nome (per esempio "Notifuse SMTP")
4. Seleziona **Accounts in this organizational directory only** (tenant singolo)
5. Clicca **Register**
6. Annota l'**Application (client) ID** e il **Directory (tenant) ID**

#### Passo 2: crea un client secret

1. Nella registrazione dell'app, vai in **Certificates & secrets**
2. Clicca **New client secret**
3. Aggiungi una descrizione e scegli la durata di validità
4. Clicca **Add**
5. **Copia subito il valore del secret** (non verrà mostrato di nuovo)

#### Passo 3: aggiungi il permesso API

1. Vai in **API permissions** → **Add a permission**
2. Seleziona **APIs my organization uses**
3. Cerca **Office 365 Exchange Online**
4. Seleziona **Application permissions**
5. Spunta **SMTP.SendAsApp**
6. Clicca **Add permissions**
7. Clicca **Grant admin consent for \[Your Organization]**

#### Passo 4: registra il service principal in Exchange Online

Questo passo viene spesso dimenticato, e senza di esso l'autenticazione fallisce. Connettiti a Exchange Online PowerShell:

```powershell
# Install module if needed
Install-Module -Name ExchangeOnlineManagement

# Connect to Exchange Online
Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com

# Register the service principal
New-ServicePrincipal -AppId <Application-Client-ID> -ObjectId <Object-ID>
```

> [!WARNING]
>
> L'`ObjectId` deve provenire da **Enterprise Applications**, non da App Registrations.
>
> Per trovare l'Object ID corretto:
>
> 1. Vai in Azure Portal → **Microsoft Entra ID** → **Enterprise Applications**
> 2. Cerca il nome della tua app
> 3. Copia l'**Object ID** dalla pagina Overview

#### Passo 5: concedi il permesso sulla casella di posta

Concedi al service principal il permesso di inviare come una casella di posta specifica:

```powershell
# Grant full access to the mailbox
Add-MailboxPermission -Identity "sender@yourdomain.com" -User <Object-ID> -AccessRights FullAccess

# Grant send-as permission
Add-RecipientPermission -Identity "sender@yourdomain.com" -Trustee <Object-ID> -AccessRights SendAs
```

#### Passo 6: attiva SMTP AUTH sulla casella di posta

Attiva SMTP AUTH sulla casella di posta di invio, nel Microsoft 365 Admin Center o con PowerShell:

**Opzione A: Microsoft 365 Admin Center**

1. Vai in **Users** → **Active users**
2. Seleziona l'utente mittente
3. Clicca la scheda **Mail** → **Manage email apps**
4. Spunta **Authenticated SMTP**
5. Clicca **Save changes**

**Opzione B: PowerShell**

```powershell
# Enable SMTP AUTH for the mailbox
Set-CASMailbox -Identity "sender@yourdomain.com" -SmtpClientAuthenticationDisabled $false
```

> [!WARNING]
>
> Se nel tuo tenant Microsoft Entra sono attivi i **Security Defaults**, SMTP AUTH è bloccato per tutta l'organizzazione. Potresti dover disattivare i Security Defaults oppure usare al loro posto criteri di accesso condizionale.

#### Passo 7: configura in Notifuse

| Campo                                | Valore                                                   |
| ------------------------------------ | -------------------------------------------------------- |
| **Host**                             | `smtp.office365.com`                                     |
| **Porta**                            | `587`                                                    |
| **Usa TLS**                          | `On`                                                     |
| **Metodo**                           | **OAuth2**                                               |
| **Provider OAuth2**                  | **Microsoft 365 / Office 365**                           |
| **Indirizzo della casella di posta** | Email del mittente (per esempio `sender@yourdomain.com`) |
| **ID tenant**                        | Il Directory (tenant) ID di Azure AD                     |
| **Client ID**                        | L'Application (client) ID di Azure                       |
| **Client secret**                    | Il valore del secret del passo 2                         |

> [!WARNING]
>
> L'**Indirizzo della casella di posta** deve corrispondere alla casella a cui hai concesso i permessi nel passo 5.

---

### OAuth2 per Gmail

![Gmail](https://www.notifuse.com/docs/assets/gmail-icon.svg)

Gmail usa il **Refresh Token Flow** per l'autenticazione.

#### Prerequisiti

- Un account Google (Gmail personale o Google Workspace)
- Accesso a Google Cloud Console
- Un terminale con `curl` installato

#### Passo 1: crea un progetto Google Cloud

1. Vai in [Google Cloud Console](https://console.cloud.google.com)
2. Crea un nuovo progetto o selezionane uno esistente
3. Attiva la **Gmail API**:
   - Vai in **APIs & Services** → **Library**
   - Cerca "Gmail API" e attivala

#### Passo 2: configura la schermata di consenso OAuth

1. Vai in **APIs & Services** → **OAuth consent screen**
2. Seleziona il tipo di utente **External** (o Internal per Workspace)
3. Compila le informazioni dell'app:
   - App name: "Notifuse" (o un nome a tua scelta)
   - User support email: la tua email
   - Developer contact: la tua email
4. Clicca **Save and Continue**
5. Nella pagina **Scopes**, clicca **Add or Remove Scopes**
6. Aggiungi lo scope `https://mail.google.com/`
7. Clicca **Save and Continue**
8. Nella pagina **Test users**, aggiungi il tuo indirizzo Gmail
9. Clicca **Save and Continue** per completare la procedura

#### Passo 3: pubblica l'app (necessario per token di lunga durata)

> [!WARNING]
>
> In modalità "Testing", i refresh token scadono dopo **7 giorni**. Pubblica l'app per ottenere refresh token permanenti.

1. Vai in **APIs & Services** → **OAuth consent screen**
2. Clicca **Publish App**
3. Conferma cliccando **Confirm**

Lo stato dell'app passa da "Testing" a "In production".

> [!NOTE]
>
> **Nessuna verifica Google per l'uso personale**
>
> Pubblicare l'app NON richiede la verifica di Google se:
>
> - hai meno di 100 utenti
> - la usi per scopi personali o interni
>
> Se durante l'autorizzazione vedi l'avviso "unverified app", clicca **Advanced** → **Go to \[App Name] (unsafe)** per proseguire.

#### Passo 4: crea le credenziali OAuth

1. Vai in **APIs & Services** → **Credentials**
2. Clicca **Create Credentials** → **OAuth client ID**
3. Seleziona **Web application**
4. Dagli un nome (per esempio "Notifuse SMTP")
5. In **Authorized redirect URIs**, clicca **Add URI**
6. Inserisci `http://localhost`
7. Clicca **Create**
8. Una finestra mostra il tuo **Client ID** e il tuo **Client Secret**: salvali entrambi

#### Passo 5: ottieni il codice di autorizzazione

Apri questo URL nel browser, sostituendo `YOUR_CLIENT_ID` con il tuo Client ID:

```
https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&scope=https://mail.google.com/&response_type=code&access_type=offline&prompt=consent
```

**Parametri importanti dell'URL:**

- `scope=https://mail.google.com/`: necessario per l'accesso SMTP
- `access_type=offline`: necessario per ricevere un refresh token
- `prompt=consent`: obbliga Google a restituire un nuovo refresh token

Dopo che hai effettuato l'accesso e concesso il permesso, il browser ti reindirizza a un indirizzo simile a questo:

```
http://localhost/?code=4/0AQSTgQF...LONG_CODE...&scope=https://mail.google.com/
```

Copia l'intero valore di `code` (tutto ciò che sta tra `code=` e `&scope`).

> [!TIP]
>
> Se il codice contiene `%2F`, sostituiscilo con `/` prima di usarlo.

#### Passo 6: scambia il codice con un refresh token

Esegui questo comando curl nel terminale, sostituendo i segnaposto con i tuoi valori:

```bash
curl -X POST https://oauth2.googleapis.com/token \
  -d "code=YOUR_AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=http://localhost" \
  -d "grant_type=authorization_code"
```

Risposta in caso di successo:

```json
{
  "access_token": "ya29.a0AfH6SMBx...",
  "expires_in": 3599,
  "refresh_token": "1//0eHusbKw...",
  "scope": "https://mail.google.com/",
  "token_type": "Bearer"
}
```

> [!WARNING]
>
> **Salva subito il tuo `refresh_token`.** Google lo restituisce solo alla prima autorizzazione. Se lo perdi, devi revocare l'accesso e autorizzare di nuovo.

#### Passo 7: configura in Notifuse

| Campo                                | Valore                       |
| ------------------------------------ | ---------------------------- |
| **Host**                             | `smtp.gmail.com`             |
| **Porta**                            | `587`                        |
| **Usa TLS**                          | `On`                         |
| **Metodo**                           | **OAuth2**                   |
| **Provider OAuth2**                  | **Google Workspace / Gmail** |
| **Indirizzo della casella di posta** | Il tuo indirizzo Gmail       |
| **Client ID**                        | Il Client ID del passo 4     |
| **Client secret**                    | Il Client Secret del passo 4 |
| **Refresh token**                    | Il refresh token del passo 6 |

#### Durata del refresh token

Con un'**app pubblicata**, il refresh token resta valido a tempo indeterminato, a meno che:

| Condizione                                                                                               | Risultato                                           |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| Il token non viene usato per **6 mesi**                                                                  | Il token scade                                      |
| Cambi la tua **password Google**                                                                         | Il token viene revocato                             |
| Superi **50 refresh token** per client                                                                   | Il token più vecchio viene revocato automaticamente |
| Revochi a mano l'accesso su [myaccount.google.com/permissions](https://myaccount.google.com/permissions) | Il token viene revocato                             |

> [!NOTE]
>
> Se il token non è più valido, ripeti i passi 5 e 6 per generare un nuovo refresh token.

---

## Elenco dei mittenti

Aggiungi gli indirizzi mittente che questa integrazione SMTP può usare:

| Campo     | Descrizione                    | Esempio                  |
| --------- | ------------------------------ | ------------------------ |
| **Nome**  | Nome visualizzato del mittente | `Support Team`           |
| **Email** | Indirizzo email del mittente   | `support@yourdomain.com` |

Clicca **Aggiungi mittente** per aggiungere più indirizzi mittente.

---

## Tipi di utilizzo

Scegli cosa invia questa integrazione SMTP dal menu **⋯** della sua scheda in **Impostazioni** → **Integrazioni** (**Usa per il marketing**, **Usa per il transazionale**), oppure nel pannello **Invio email** della stessa pagina:

| Opzione                      | Descrizione                                        |
| ---------------------------- | -------------------------------------------------- |
| **Usa per il transazionale** | Reset della password, conferme d'ordine, notifiche |
| **Usa per il marketing**     | Newsletter, campagne promozionali, annunci         |

Scegli entrambe le opzioni per inviare ogni tipo di email con la stessa configurazione SMTP.

---

## Limitazioni

SMTP non ha webhook, quindi da un'integrazione SMTP Notifuse non riceve aggiornamenti sullo stato di consegna, notifiche di bounce né segnalazioni di spam o abuso.

> [!NOTE]
>
> Notifuse aggiunge il **tracciamento di aperture e click** a tutte le email, qualunque sia il provider email.

Per i webhook di consegna e le altre funzioni dei provider, usa un servizio email come [Mailgun](https://www.notifuse.com/it/docs/integrations/mailgun.md), [Postmark](https://www.notifuse.com/it/docs/integrations/postmark.md) o [SparkPost](https://www.notifuse.com/it/docs/integrations/sparkpost.md).

---

## Server SMTP comuni

| Provider      | Host                              | Porta | TLS | Tipo di autenticazione |
| ------------- | --------------------------------- | ----- | --- | ---------------------- |
| Gmail         | `smtp.gmail.com`                  | `587` | Sì  | OAuth2 (obbligatorio)  |
| Microsoft 365 | `smtp.office365.com`              | `587` | Sì  | OAuth2 (obbligatorio)  |
| Amazon SES    | `email-smtp.region.amazonaws.com` | `587` | Sì  | Basic Auth             |
| SendGrid      | `smtp.sendgrid.net`               | `587` | Sì  | Basic Auth             |
| Mailgun       | `smtp.mailgun.org`                | `587` | Sì  | Basic Auth             |

> [!NOTE]
>
> Gmail e Microsoft 365 hanno deprecato l'autenticazione di base: per loro usa OAuth2.

---

## Risoluzione dei problemi

### Microsoft 365: "535 5.7.3 Authentication unsuccessful"

Di solito questo errore significa che:

1. Il service principal non è registrato in Exchange Online (passo 4)
2. I permessi sulla casella di posta non sono stati concessi (passo 5)
3. L'**Indirizzo della casella di posta** non corrisponde alla casella autorizzata

### Gmail: "unauthorized_client"

Questo errore significa che:

1. Il refresh token è stato generato con un Client ID o un Client Secret diversi
2. Devi rigenerare il refresh token con le credenziali attuali

### Gmail: "invalid_grant"

Questo errore significa che:

1. Il refresh token è scaduto (7 giorni in modalità Testing)
2. L'utente ha cambiato la password Google
3. Il token è stato revocato o ha superato il limite di 50 token

**Soluzione**: genera un nuovo refresh token seguendo i passi 5 e 6.

---

## Test

Clicca **Invia un’email di prova** in cima al modulo dell'integrazione, oppure **Invia prova** sulla sua scheda, per verificare la configurazione.
