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

> SMTP mit Basic Auth oder OAuth2 als E-Mail-Anbieter in Notifuse einrichten.

Die SMTP-Integration verbindet jeden SMTP-fähigen E-Mail-Dienst mit Notifuse, mit Passwort-Authentifizierung oder mit OAuth2 für Microsoft 365 und Gmail.

## Konfiguration

Gehen Sie zu **Einstellungen** → **Integrationen**, klicken Sie auf **Integration hinzufügen** und wählen Sie dann **SMTP** unter **E-Mail-Versand**. Das Formular öffnet sich als ganze Seite.

### Grundeinstellungen

| Feld                | Beschreibung                                                                                                                                   | Beispiel              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| **Name**            | Anzeigename dieser SMTP-Konfiguration                                                                                                          | `Company SMTP`        |
| **Host**            | Hostname des SMTP-Servers                                                                                                                      | `smtp.gmail.com`      |
| **Port**            | Port des SMTP-Servers: 587 für STARTTLS, 465 für TLS ab dem ersten Byte, 25 unverschlüsselt                                                    | `587`                 |
| **Verschlüsselung** | Der Schalter **TLS verwenden**. An: STARTTLS, oder TLS ab dem ersten Byte auf Port 465. Aus: Klartext                                          | `On`                  |
| **EHLO-Hostname**   | Hostname, der mit dem SMTP-Befehl EHLO gesendet wird. Ohne Angabe wird der Host verwendet. Nützlich, wenn ein Server `EHLO localhost` ablehnt. | `mail.yourdomain.com` |

### Authentifizierungsart

Wählen Sie im Bereich **Authentifizierung** unter **Methode** eine von zwei Optionen:

| Option                        | Beschreibung                     | Einsatzzweck                             |
| ----------------------------- | -------------------------------- | ---------------------------------------- |
| **Benutzername und Passwort** | Basic Authentication             | Die meisten SMTP-Server, App-Passwörter  |
| **OAuth2**                    | Token-basierte Authentifizierung | Microsoft 365, Gmail (seit 2024 Pflicht) |

---

## Basic Authentication

Für SMTP-Server, die ein Passwort annehmen, oder Dienste, die App-Passwörter unterstützen.

| Feld             | Beschreibung                                                                                           | Beispiel               |
| ---------------- | ------------------------------------------------------------------------------------------------------ | ---------------------- |
| **Benutzername** | Benutzername für die Authentifizierung. Leer lassen bei einem Server, der Mails ohne Anmeldung annimmt | `your-email@gmail.com` |
| **Passwort**     | Passwort für die Authentifizierung                                                                     | `your-app-password`    |

---

## OAuth2-Authentifizierung

Microsoft 365 und Gmail haben Basic Authentication abgekündigt und verlangen deshalb OAuth2.

### Microsoft 365 OAuth2

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

Microsoft 365 nutzt für die Authentifizierung zwischen Servern den **Client Credentials Flow**.

#### Voraussetzungen

- Ein Microsoft 365 Business-Konto (kein privates Outlook.com)
- Administratorzugriff auf Azure AD
- Administratorzugriff auf Exchange Online

#### Schritt 1: Azure-AD-Anwendung registrieren

1. Gehen Sie im [Azure Portal](https://portal.azure.com) zu **Azure Active Directory** → **App registrations**
2. Klicken Sie auf **New registration**
3. Geben Sie einen Namen ein (z. B. „Notifuse SMTP“)
4. Wählen Sie **Accounts in this organizational directory only** (Single Tenant)
5. Klicken Sie auf **Register**
6. Notieren Sie **Application (client) ID** und **Directory (tenant) ID**

#### Schritt 2: Client Secret erstellen

1. Gehen Sie in Ihrer App-Registrierung zu **Certificates & secrets**
2. Klicken Sie auf **New client secret**
3. Geben Sie eine Beschreibung ein und wählen Sie die Gültigkeitsdauer
4. Klicken Sie auf **Add**
5. **Kopieren Sie den Wert des Secrets sofort** (er wird nicht noch einmal angezeigt)

#### Schritt 3: API-Berechtigung hinzufügen

1. Gehen Sie zu **API permissions** → **Add a permission**
2. Wählen Sie **APIs my organization uses**
3. Suchen Sie nach **Office 365 Exchange Online**
4. Wählen Sie **Application permissions**
5. Kreuzen Sie **SMTP.SendAsApp** an
6. Klicken Sie auf **Add permissions**
7. Klicken Sie auf **Grant admin consent for \[Your Organization]**

#### Schritt 4: Service Principal in Exchange Online registrieren

Dieser Schritt wird oft vergessen, und ohne ihn schlägt die Authentifizierung fehl. Verbinden Sie sich mit 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]
>
> Die `ObjectId` muss aus **Enterprise Applications** stammen, nicht aus App Registrations.
>
> So finden Sie die richtige Object ID:
>
> 1. Gehen Sie im Azure Portal zu **Microsoft Entra ID** → **Enterprise Applications**
> 2. Suchen Sie nach dem Namen Ihrer App
> 3. Kopieren Sie die **Object ID** von der Übersichtsseite

#### Schritt 5: Postfachberechtigung erteilen

Erteilen Sie dem Service Principal die Berechtigung, im Namen eines bestimmten Postfachs zu senden:

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

#### Schritt 6: SMTP AUTH für das Postfach aktivieren

Aktivieren Sie SMTP AUTH für das sendende Postfach, im Microsoft 365 Admin Center oder per PowerShell:

**Option A: Microsoft 365 Admin Center**

1. Gehen Sie zu **Users** → **Active users**
2. Wählen Sie den Absender-Benutzer aus
3. Klicken Sie auf den Reiter **Mail** → **Manage email apps**
4. Kreuzen Sie **Authenticated SMTP** an
5. Klicken Sie auf **Save changes**

**Option B: PowerShell**

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

> [!WARNING]
>
> Wenn in Ihrem Microsoft-Entra-Mandanten **Security Defaults** aktiviert ist, ist SMTP AUTH für die gesamte Organisation gesperrt. Unter Umständen müssen Sie die Security Defaults deaktivieren oder stattdessen Richtlinien für bedingten Zugriff verwenden.

#### Schritt 7: In Notifuse einrichten

| Feld                | Wert                                                         |
| ------------------- | ------------------------------------------------------------ |
| **Host**            | `smtp.office365.com`                                         |
| **Port**            | `587`                                                        |
| **TLS verwenden**   | `On`                                                         |
| **Methode**         | **OAuth2**                                                   |
| **OAuth2-Anbieter** | **Microsoft 365 / Office 365**                               |
| **Postfachadresse** | E-Mail-Adresse des Absenders (z. B. `sender@yourdomain.com`) |
| **Mandanten-ID**    | Ihre Directory (tenant) ID aus Azure AD                      |
| **Client-ID**       | Application (client) ID aus Azure                            |
| **Client Secret**   | Wert des Secrets aus Schritt 2                               |

> [!WARNING]
>
> Die **Postfachadresse** muss dem Postfach entsprechen, dem Sie in Schritt 5 Berechtigungen erteilt haben.

---

### Gmail OAuth2

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

Gmail nutzt für die Authentifizierung den **Refresh Token Flow**.

#### Voraussetzungen

- Ein Google-Konto (privates Gmail oder Google Workspace)
- Zugriff auf die Google Cloud Console
- Ein Terminal mit installiertem `curl`

#### Schritt 1: Google-Cloud-Projekt erstellen

1. Gehen Sie zur [Google Cloud Console](https://console.cloud.google.com)
2. Erstellen Sie ein neues Projekt oder wählen Sie ein vorhandenes aus
3. Aktivieren Sie die **Gmail API**:
   - Gehen Sie zu **APIs & Services** → **Library**
   - Suchen Sie nach „Gmail API“ und aktivieren Sie sie

#### Schritt 2: OAuth-Zustimmungsbildschirm einrichten

1. Gehen Sie zu **APIs & Services** → **OAuth consent screen**
2. Wählen Sie den Nutzertyp **External** (oder Internal bei Workspace)
3. Geben Sie die App-Informationen ein:
   - App name: „Notifuse“ (oder ein Name Ihrer Wahl)
   - User support email: Ihre E-Mail-Adresse
   - Developer contact: Ihre E-Mail-Adresse
4. Klicken Sie auf **Save and Continue**
5. Klicken Sie auf der Seite **Scopes** auf **Add or Remove Scopes**
6. Fügen Sie den Scope `https://mail.google.com/` hinzu
7. Klicken Sie auf **Save and Continue**
8. Fügen Sie auf der Seite **Test users** Ihre Gmail-Adresse hinzu
9. Klicken Sie auf **Save and Continue**, um den Assistenten abzuschließen

#### Schritt 3: App veröffentlichen (nötig für langlebige Tokens)

> [!WARNING]
>
> Im Modus „Testing“ laufen Refresh-Tokens nach **7 Tagen** ab. Veröffentlichen Sie Ihre App, um dauerhafte Refresh-Tokens zu erhalten.

1. Gehen Sie zu **APIs & Services** → **OAuth consent screen**
2. Klicken Sie auf **Publish App**
3. Bestätigen Sie mit **Confirm**

Der Status der App wechselt von „Testing“ zu „In production“.

> [!NOTE]
>
> **Keine Google-Verifizierung für den persönlichen Gebrauch nötig**
>
> Eine Veröffentlichung Ihrer App erfordert KEINE Verifizierung durch Google, wenn:
>
> - Sie weniger als 100 Nutzer haben
> - Sie die App für persönliche oder interne Zwecke nutzen
>
> Wenn beim Autorisieren die Warnung „unverified app“ erscheint, klicken Sie auf **Advanced** → **Go to \[App Name] (unsafe)**, um fortzufahren.

#### Schritt 4: OAuth-Zugangsdaten erstellen

1. Gehen Sie zu **APIs & Services** → **Credentials**
2. Klicken Sie auf **Create Credentials** → **OAuth client ID**
3. Wählen Sie **Web application**
4. Geben Sie einen Namen ein (z. B. „Notifuse SMTP“)
5. Klicken Sie unter **Authorized redirect URIs** auf **Add URI**
6. Geben Sie `http://localhost` ein
7. Klicken Sie auf **Create**
8. Ein Dialog zeigt Ihre **Client ID** und Ihr **Client Secret**: Speichern Sie beide

#### Schritt 5: Autorisierungscode abrufen

Öffnen Sie diese URL in Ihrem Browser und setzen Sie Ihre Client-ID anstelle von `YOUR_CLIENT_ID` ein:

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

**Wichtige URL-Parameter:**

- `scope=https://mail.google.com/`: nötig für den SMTP-Zugriff
- `access_type=offline`: nötig, um ein Refresh-Token zu erhalten
- `prompt=consent`: zwingt Google, ein neues Refresh-Token auszugeben

Nachdem Sie sich angemeldet und die Berechtigung erteilt haben, leitet der Browser auf eine Adresse wie diese weiter:

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

Kopieren Sie den gesamten Wert von `code` (alles zwischen `code=` und `&scope`).

> [!TIP]
>
> Enthält der Code `%2F`, ersetzen Sie es vor der Verwendung durch `/`.

#### Schritt 6: Code gegen ein Refresh-Token tauschen

Führen Sie diesen curl-Befehl in Ihrem Terminal aus und ersetzen Sie die Platzhalter durch Ihre Werte:

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

Erfolgreiche Antwort:

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

> [!WARNING]
>
> **Speichern Sie Ihr `refresh_token` jetzt.** Google gibt es nur bei der ersten Autorisierung zurück. Wenn Sie es verlieren, müssen Sie den Zugriff widerrufen und erneut autorisieren.

#### Schritt 7: In Notifuse einrichten

| Feld                | Wert                         |
| ------------------- | ---------------------------- |
| **Host**            | `smtp.gmail.com`             |
| **Port**            | `587`                        |
| **TLS verwenden**   | `On`                         |
| **Methode**         | **OAuth2**                   |
| **OAuth2-Anbieter** | **Google Workspace / Gmail** |
| **Postfachadresse** | Ihre Gmail-Adresse           |
| **Client-ID**       | Client ID aus Schritt 4      |
| **Client Secret**   | Client Secret aus Schritt 4  |
| **Refresh-Token**   | Refresh-Token aus Schritt 6  |

#### Lebensdauer des Refresh-Tokens

Bei einer **veröffentlichten App** bleibt das Refresh-Token unbegrenzt gültig, außer wenn:

| Bedingung                                                                                                             | Folge                                         |
| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Das Token **6 Monate** lang nicht genutzt wird                                                                        | Das Token läuft ab                            |
| Sie Ihr **Google-Passwort** ändern                                                                                    | Das Token wird widerrufen                     |
| Sie **50 Refresh-Tokens** pro Client überschreiten                                                                    | Das älteste Token wird automatisch widerrufen |
| Sie den Zugriff unter [myaccount.google.com/permissions](https://myaccount.google.com/permissions) manuell widerrufen | Das Token wird widerrufen                     |

> [!NOTE]
>
> Wird Ihr Token ungültig, wiederholen Sie die Schritte 5 und 6, um ein neues Refresh-Token zu erzeugen.

---

## Absenderliste

Fügen Sie die Absenderadressen hinzu, die diese SMTP-Integration verwenden darf:

| Feld       | Beschreibung                 | Beispiel                 |
| ---------- | ---------------------------- | ------------------------ |
| **Name**   | Anzeigename des Absenders    | `Support Team`           |
| **E-Mail** | E-Mail-Adresse des Absenders | `support@yourdomain.com` |

Klicken Sie auf **Absender hinzufügen**, um weitere Absenderadressen anzulegen.

---

## Verwendungszwecke

Legen Sie fest, was diese SMTP-Integration versendet: im Menü **⋯** ihrer Karte unter **Einstellungen** → **Integrationen** (**Für Marketing verwenden**, **Für Transaktionales verwenden**) oder im Bereich **E-Mail-Versand** derselben Seite:

| Option                            | Beschreibung                                                       |
| --------------------------------- | ------------------------------------------------------------------ |
| **Für Transaktionales verwenden** | Passwort-Zurücksetzungen, Bestellbestätigungen, Benachrichtigungen |
| **Für Marketing verwenden**       | Newsletter, Werbekampagnen, Ankündigungen                          |

Wählen Sie beides, um alle Arten von E-Mails über dieselbe SMTP-Konfiguration zu versenden.

---

## Einschränkungen

SMTP hat keine Webhooks. Notifuse erhält von einer SMTP-Integration daher keine Statusmeldungen zur Zustellung, keine Bounce-Benachrichtigungen und keine Spam- oder Missbrauchsbeschwerden.

> [!NOTE]
>
> Notifuse fügt allen E-Mails **Öffnungs- und Klick-Tracking** hinzu, unabhängig vom E-Mail-Anbieter.

Für Zustell-Webhooks und die weiteren Funktionen eines Anbieters verwenden Sie einen E-Mail-Dienstleister wie [Mailgun](https://www.notifuse.com/de/docs/integrations/mailgun.md), [Postmark](https://www.notifuse.com/de/docs/integrations/postmark.md) oder [SparkPost](https://www.notifuse.com/de/docs/integrations/sparkpost.md).

---

## Gängige SMTP-Server

| Anbieter      | Host                              | Port  | TLS | Authentifizierung |
| ------------- | --------------------------------- | ----- | --- | ----------------- |
| Gmail         | `smtp.gmail.com`                  | `587` | Ja  | OAuth2 (Pflicht)  |
| Microsoft 365 | `smtp.office365.com`              | `587` | Ja  | OAuth2 (Pflicht)  |
| Amazon SES    | `email-smtp.region.amazonaws.com` | `587` | Ja  | Basic Auth        |
| SendGrid      | `smtp.sendgrid.net`               | `587` | Ja  | Basic Auth        |
| Mailgun       | `smtp.mailgun.org`                | `587` | Ja  | Basic Auth        |

> [!NOTE]
>
> Gmail und Microsoft 365 haben Basic Authentication abgekündigt: Verwenden Sie dort OAuth2.

---

## Fehlerbehebung

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

Dieser Fehler bedeutet meist:

1. Der Service Principal ist nicht in Exchange Online registriert (Schritt 4)
2. Die Postfachberechtigungen wurden nicht erteilt (Schritt 5)
3. Die **Postfachadresse** entspricht nicht dem berechtigten Postfach

### Gmail: "unauthorized_client"

Dieser Fehler bedeutet:

1. Das Refresh-Token wurde mit einer anderen Client-ID oder einem anderen Client Secret erzeugt
2. Erzeugen Sie das Refresh-Token mit Ihren aktuellen Zugangsdaten neu

### Gmail: "invalid_grant"

Dieser Fehler bedeutet:

1. Das Refresh-Token ist abgelaufen (7 Tage im Modus Testing)
2. Der Nutzer hat sein Google-Passwort geändert
3. Das Token wurde widerrufen, oder die Grenze von 50 Tokens wurde überschritten

**Lösung**: Erzeugen Sie ein neues Refresh-Token nach den Schritten 5 und 6.

---

## Testen

Klicken Sie oben im Integrationsformular auf **Test-E-Mail senden** oder auf der Karte auf **Test senden**, um Ihre Konfiguration zu prüfen.
