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

> Configurer SMTP comme fournisseur d'email dans Notifuse, avec Basic Auth ou OAuth2.

L'intégration SMTP connecte à Notifuse n'importe quel service d'email compatible SMTP, avec une authentification par mot de passe ou avec OAuth2 pour Microsoft 365 et Gmail.

## Configuration

Allez dans **Paramètres** → **Intégrations**, cliquez sur **Ajouter une intégration**, puis choisissez **SMTP** sous **Envoi d'emails**. Le formulaire s'ouvre en pleine page.

### Paramètres de base

| Champ               | Description                                                                                                                       | Exemple               |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| **Nom**             | Nom d'affichage de cette configuration SMTP                                                                                       | `Company SMTP`        |
| **Hôte**            | Nom d'hôte du serveur SMTP                                                                                                        | `smtp.gmail.com`      |
| **Port**            | Numéro de port du serveur SMTP : 587 pour STARTTLS, 465 pour TLS dès le premier octet, 25 sans chiffrement                        | `587`                 |
| **Chiffrement**     | L'interrupteur **Utiliser TLS**. Activé : STARTTLS, ou TLS dès le premier octet sur le port 465. Désactivé : texte en clair       | `On`                  |
| **Nom d'hôte EHLO** | Nom d'hôte envoyé avec la commande SMTP EHLO. Vide, il prend la valeur de l'hôte. Utile quand un serveur refuse `EHLO localhost`. | `mail.yourdomain.com` |

### Type d'authentification

Choisissez l'une des deux options de **Méthode**, dans le panneau **Authentification** :

| Option                                | Description                | Cas d'usage                                               |
| ------------------------------------- | -------------------------- | --------------------------------------------------------- |
| **Nom d'utilisateur et mot de passe** | Authentification basique   | La plupart des serveurs SMTP, mots de passe d'application |
| **OAuth2**                            | Authentification par jeton | Microsoft 365, Gmail (obligatoire depuis 2024)            |

---

## Authentification basique

Pour les serveurs SMTP qui acceptent un mot de passe, ou les services qui prennent en charge les mots de passe d'application.

| Champ                 | Description                                                                                                 | Exemple                |
| --------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------- |
| **Nom d'utilisateur** | Nom d'utilisateur d'authentification. Laissez-le vide pour un serveur qui accepte les emails sans connexion | `your-email@gmail.com` |
| **Mot de passe**      | Mot de passe d'authentification                                                                             | `your-app-password`    |

---

## Authentification OAuth2

Microsoft 365 et Gmail ont abandonné l'authentification basique : ils exigent OAuth2.

### OAuth2 pour Microsoft 365

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

Microsoft 365 utilise le **flux Client Credentials** pour l'authentification de serveur à serveur.

#### Prérequis

- Un compte Microsoft 365 Business (pas un compte personnel Outlook.com)
- Un accès administrateur à Azure AD
- Un accès administrateur à Exchange Online

#### Étape 1 : enregistrer une application Azure AD

1. Allez dans le [Azure Portal](https://portal.azure.com) → **Azure Active Directory** → **App registrations**
2. Cliquez sur **New registration**
3. Saisissez un nom (par exemple « Notifuse SMTP »)
4. Sélectionnez **Accounts in this organizational directory only** (locataire unique)
5. Cliquez sur **Register**
6. Notez l'**Application (client) ID** et le **Directory (tenant) ID**

#### Étape 2 : créer un secret client

1. Dans l'enregistrement de votre application, allez dans **Certificates & secrets**
2. Cliquez sur **New client secret**
3. Ajoutez une description et choisissez une durée de validité
4. Cliquez sur **Add**
5. **Copiez tout de suite la valeur du secret** (elle ne sera plus affichée)

#### Étape 3 : ajouter une permission d'API

1. Allez dans **API permissions** → **Add a permission**
2. Sélectionnez **APIs my organization uses**
3. Cherchez **Office 365 Exchange Online**
4. Sélectionnez **Application permissions**
5. Cochez **SMTP.SendAsApp**
6. Cliquez sur **Add permissions**
7. Cliquez sur **Grant admin consent for \[Your Organization]**

#### Étape 4 : enregistrer le principal de service dans Exchange Online

Cette étape est souvent oubliée, et l'authentification échoue sans elle. Connectez-vous à 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` doit venir de **Enterprise Applications**, pas de App Registrations.
>
> Pour trouver le bon Object ID :
>
> 1. Allez dans le Azure Portal → **Microsoft Entra ID** → **Enterprise Applications**
> 2. Cherchez le nom de votre application
> 3. Copiez l'**Object ID** depuis la page Overview

#### Étape 5 : accorder la permission sur la boîte mail

Autorisez le principal de service à envoyer au nom d'une boîte mail précise :

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

#### Étape 6 : activer SMTP AUTH sur la boîte mail

Activez SMTP AUTH sur la boîte mail d'envoi, dans le Microsoft 365 Admin Center ou avec PowerShell :

**Option A : Microsoft 365 Admin Center**

1. Allez dans **Users** → **Active users**
2. Sélectionnez l'utilisateur expéditeur
3. Cliquez sur l'onglet **Mail** → **Manage email apps**
4. Cochez **Authenticated SMTP**
5. Cliquez sur **Save changes**

**Option B : PowerShell**

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

> [!WARNING]
>
> Si les **Security Defaults** sont activés dans votre locataire Microsoft Entra, SMTP AUTH est bloqué pour toute l'organisation. Vous devrez peut-être désactiver les Security Defaults ou utiliser plutôt des stratégies Conditional Access.

#### Étape 7 : configurer dans Notifuse

| Champ                        | Valeur                                                      |
| ---------------------------- | ----------------------------------------------------------- |
| **Hôte**                     | `smtp.office365.com`                                        |
| **Port**                     | `587`                                                       |
| **Utiliser TLS**             | `On`                                                        |
| **Méthode**                  | **OAuth2**                                                  |
| **Fournisseur OAuth2**       | **Microsoft 365 / Office 365**                              |
| **Adresse de la boîte mail** | Email de l'expéditeur (par exemple `sender@yourdomain.com`) |
| **ID du tenant**             | Le Directory (tenant) ID de votre Azure AD                  |
| **Client ID**                | L'Application (client) ID d'Azure                           |
| **Client secret**            | La valeur du secret de l'étape 2                            |

> [!WARNING]
>
> L'**Adresse de la boîte mail** doit correspondre à la boîte mail sur laquelle vous avez accordé les permissions à l'étape 5.

---

### OAuth2 pour Gmail

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

Gmail utilise le **flux Refresh Token** pour l'authentification.

#### Prérequis

- Un compte Google (Gmail personnel ou Google Workspace)
- Un accès à la Google Cloud Console
- Un terminal avec `curl` installé

#### Étape 1 : créer un projet Google Cloud

1. Allez sur la [Google Cloud Console](https://console.cloud.google.com)
2. Créez un projet ou sélectionnez-en un existant
3. Activez la **Gmail API** :
   - Allez dans **APIs & Services** → **Library**
   - Cherchez « Gmail API » et activez-la

#### Étape 2 : configurer l'écran de consentement OAuth

1. Allez dans **APIs & Services** → **OAuth consent screen**
2. Sélectionnez le type d'utilisateur **External** (ou Internal pour Workspace)
3. Renseignez les informations de l'application :
   - App name : « Notifuse » (ou le nom de votre choix)
   - User support email : votre email
   - Developer contact : votre email
4. Cliquez sur **Save and Continue**
5. Sur la page **Scopes**, cliquez sur **Add or Remove Scopes**
6. Ajoutez le scope `https://mail.google.com/`
7. Cliquez sur **Save and Continue**
8. Sur la page **Test users**, ajoutez votre adresse Gmail
9. Cliquez sur **Save and Continue** pour terminer l'assistant

#### Étape 3 : publier votre application (nécessaire pour des jetons durables)

> [!WARNING]
>
> En mode « Testing », les refresh tokens expirent au bout de **7 jours**. Publiez votre application pour obtenir des refresh tokens permanents.

1. Allez dans **APIs & Services** → **OAuth consent screen**
2. Cliquez sur **Publish App**
3. Validez en cliquant sur **Confirm**

Le statut de l'application passe de « Testing » à « In production ».

> [!NOTE]
>
> **Pas de vérification Google pour un usage personnel**
>
> Publier votre application ne demande PAS de vérification par Google si :
>
> - vous avez moins de 100 utilisateurs ;
> - vous l'utilisez à des fins personnelles ou internes.
>
> Si un avertissement « unverified app » s'affiche au moment de l'autorisation, cliquez sur **Advanced** → **Go to \[App Name] (unsafe)** pour continuer.

#### Étape 4 : créer les identifiants OAuth

1. Allez dans **APIs & Services** → **Credentials**
2. Cliquez sur **Create Credentials** → **OAuth client ID**
3. Sélectionnez **Web application**
4. Donnez-lui un nom (par exemple « Notifuse SMTP »)
5. Sous **Authorized redirect URIs**, cliquez sur **Add URI**
6. Saisissez `http://localhost`
7. Cliquez sur **Create**
8. Une fenêtre affiche votre **Client ID** et votre **Client Secret** : notez les deux

#### Étape 5 : obtenir le code d'autorisation

Ouvrez cette URL dans votre navigateur, en remplaçant `YOUR_CLIENT_ID` par votre 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
```

**Paramètres importants de l'URL :**

- `scope=https://mail.google.com/` : nécessaire pour l'accès SMTP
- `access_type=offline` : nécessaire pour recevoir un refresh token
- `prompt=consent` : oblige Google à renvoyer un nouveau refresh token

Une fois que vous vous êtes connecté et avez donné votre accord, le navigateur est redirigé vers une adresse de ce type :

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

Copiez toute la valeur de `code` (tout ce qui se trouve entre `code=` et `&scope`).

> [!TIP]
>
> Si le code contient `%2F`, remplacez-le par `/` avant de l'utiliser.

#### Étape 6 : échanger le code contre un refresh token

Lancez cette commande curl dans votre terminal, en remplaçant les valeurs d'exemple par les vôtres :

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

Réponse en cas de succès :

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

> [!WARNING]
>
> **Enregistrez votre `refresh_token` maintenant.** Google ne le renvoie qu'à la première autorisation. Si vous le perdez, vous devez révoquer l'accès et autoriser à nouveau.

#### Étape 7 : configurer dans Notifuse

| Champ                        | Valeur                        |
| ---------------------------- | ----------------------------- |
| **Hôte**                     | `smtp.gmail.com`              |
| **Port**                     | `587`                         |
| **Utiliser TLS**             | `On`                          |
| **Méthode**                  | **OAuth2**                    |
| **Fournisseur OAuth2**       | **Google Workspace / Gmail**  |
| **Adresse de la boîte mail** | Votre adresse Gmail           |
| **Client ID**                | Le Client ID de l'étape 4     |
| **Client secret**            | Le Client Secret de l'étape 4 |
| **Jeton d'actualisation**    | Le refresh token de l'étape 6 |

#### Durée de vie du refresh token

Avec une **application publiée**, le refresh token reste valide sans limite de durée, sauf dans ces cas :

| Situation                                                                                                        | Résultat                                            |
| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| Jeton inutilisé pendant **6 mois**                                                                               | Le jeton expire                                     |
| Vous changez votre **mot de passe Google**                                                                       | Le jeton est révoqué                                |
| Vous dépassez **50 refresh tokens** par client                                                                   | Le jeton le plus ancien est révoqué automatiquement |
| Vous révoquez l'accès vous-même sur [myaccount.google.com/permissions](https://myaccount.google.com/permissions) | Le jeton est révoqué                                |

> [!NOTE]
>
> Si votre jeton n'est plus valide, refaites les étapes 5 et 6 pour générer un nouveau refresh token.

---

## Liste des expéditeurs

Ajoutez les adresses d'expéditeur que cette intégration SMTP peut utiliser :

| Champ     | Description                     | Exemple                  |
| --------- | ------------------------------- | ------------------------ |
| **Nom**   | Nom d'affichage de l'expéditeur | `Support Team`           |
| **Email** | Adresse email de l'expéditeur   | `support@yourdomain.com` |

Cliquez sur **Ajouter un expéditeur** pour ajouter plusieurs adresses d'expéditeur.

---

## Types d'usage

Choisissez ce qu'envoie cette intégration SMTP depuis le menu **⋯** de sa carte dans **Paramètres** → **Intégrations** (**Utiliser pour le marketing**, **Utiliser pour le transactionnel**), ou dans le panneau **Envoi d'emails** de cette page :

| Option                              | Description                                                                 |
| ----------------------------------- | --------------------------------------------------------------------------- |
| **Utiliser pour le transactionnel** | Réinitialisations de mot de passe, confirmations de commande, notifications |
| **Utiliser pour le marketing**      | Newsletters, campagnes promotionnelles, annonces                            |

Choisissez les deux pour envoyer tous les types d'emails par la même configuration SMTP.

---

## Limites

SMTP n'a pas de webhooks : Notifuse ne reçoit d'une intégration SMTP aucune mise à jour du statut de livraison, aucune notification de rebond et aucune plainte pour spam ou abus.

> [!NOTE]
>
> Notifuse ajoute le **suivi des ouvertures et des clics** à tous les emails, quel que soit le fournisseur d'email.

Pour les webhooks de livraison et les autres fonctions des fournisseurs, utilisez un fournisseur de services d'email comme [Mailgun](https://www.notifuse.com/fr/docs/integrations/mailgun.md), [Postmark](https://www.notifuse.com/fr/docs/integrations/postmark.md) ou [SparkPost](https://www.notifuse.com/fr/docs/integrations/sparkpost.md).

---

## Serveurs SMTP courants

| Fournisseur   | Hôte                              | Port  | TLS | Type d'authentification |
| ------------- | --------------------------------- | ----- | --- | ----------------------- |
| Gmail         | `smtp.gmail.com`                  | `587` | Oui | OAuth2 (obligatoire)    |
| Microsoft 365 | `smtp.office365.com`              | `587` | Oui | OAuth2 (obligatoire)    |
| Amazon SES    | `email-smtp.region.amazonaws.com` | `587` | Oui | Basic Auth              |
| SendGrid      | `smtp.sendgrid.net`               | `587` | Oui | Basic Auth              |
| Mailgun       | `smtp.mailgun.org`                | `587` | Oui | Basic Auth              |

> [!NOTE]
>
> Gmail et Microsoft 365 ont abandonné l'authentification basique : utilisez OAuth2 pour eux.

---

## Dépannage

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

Cette erreur signifie généralement :

1. Le principal de service n'est pas enregistré dans Exchange Online (étape 4)
2. Les permissions sur la boîte mail n'ont pas été accordées (étape 5)
3. L'**Adresse de la boîte mail** ne correspond pas à la boîte mail autorisée

### Gmail : "unauthorized_client"

Cette erreur signifie :

1. Le refresh token a été généré avec un autre Client ID ou Client Secret
2. Générez à nouveau le refresh token avec vos identifiants actuels

### Gmail : "invalid_grant"

Cette erreur signifie :

1. Le refresh token a expiré (7 jours en mode Testing)
2. L'utilisateur a changé son mot de passe Google
3. Le jeton a été révoqué ou a dépassé la limite de 50 jetons

**Solution** : générez un nouveau refresh token en suivant les étapes 5 et 6.

---

## Test

Cliquez sur **Envoyer un e-mail de test** en haut du formulaire de l'intégration, ou sur **Envoyer un test** sur sa carte, pour vérifier votre configuration.
