# Benachrichtigungskanäle

Eine Schritt-für-Schritt-Anleitung zum Telefonanschluss finden Sie unter [Verbinden Sie die App](connect-app.md).

## Konfigurieren Sie in der Konsole

1. Öffnen Sie **Benachrichtigungen** und wählen Sie Bark, Pushover, Webhook oder Mailwake App.
2. Füllen Sie die Felder des ausgewählten Kanals unten aus. Für die Mailwake-App geben Sie zuerst [Koppeln Sie das Telefon](connect-app.md) ein und wählen dann das empfangende Telefon aus.
3. Wählen Sie die Vorschau, die Benachrichtigungssprache und die Anzahl der Wiederholungen. Bei einem Wiederholungszähler von 0 erfolgt ein Versuch.
4. Speichern und dann explizit eine Testbenachrichtigung senden. Überprüfen Sie den Telefon- oder Webhook-Empfänger und das Zustellungsergebnis.

Die Einstellungen gelten für alle Postfächer. Durch das Ändern der Einstellungen bleiben in der Warteschlange befindliche Arbeiten gemäß ihrem bestehenden Lieferplan erhalten. Überprüfen Sie zukünftiges Verhalten mit einer neuen Nachricht.

## Kanalkonfiguration

Konfigurieren Sie den globalen Kanal über `/api/v1/settings/delivery` und senden Sie seinen aktuellen `revision`. Kanal, Vorschau, Wiederholungsanzahl und Benachrichtigungssprache gelten für alle Postfächer. Alle Anmeldeinformationen sind verschlüsselt und nur schreibbar; Bei unverändertem Ziel bleiben ausgelassene Zugangsdaten erhalten. Beim Ändern einer gespeicherten Bark-Adresse muss der Geräteschlüssel erneut eingegeben werden.

| Kanal      | Parameter                                                                                                                                        | Anmeldeinformationen                                                 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| `bark`     | `bark.endpoint`, Standard `https://api.day.app`                                                                                                  | `bark.key`                                                           |
| `pushover` | keiner                                                                                                                                           | `pushover.token` , `pushover.user`                                   |
| `webhook`  | HTTPS, Abfrage erlaubt                                                                                                                           | `webhook.url` und `webhook.secret` (mindestens 32 Nicht-Leerzeichen) |
| `native`   | Standardmäßig offizieller Produktions-Push-Zustelldienst; überschreiben mit `MAILWAKE_RELAY_URL` ; Koppeln Sie Telefone in der App-Autorisierung | Lokal generierte, verschlüsselte Außenpostenidentität                |

Webhook-URLs sind schreibgeschützt, da Pfade und Abfragen Routing-Anmeldeinformationen enthalten können. `preview` akzeptiert `off` oder `subject`; `retry_count` akzeptiert 0–9 und ist standardmäßig auf 0 eingestellt; `language` akzeptiert [neun Katalogcodes und ihre regionalen Aliase](api.md#sprachen-und-fehlercodes) und ist standardmäßig auf `en` eingestellt. Bark und Pushover zeigen nur das Subjekt mit `subject`; Der Webhook behält den strukturierten Absender und Betreff bei, während sein `message` ebenfalls nur den Betreff enthält. `off` (und ein leerer Betreff) verwendet die lokalisierte Nachricht „Neue E-Mail“. Titel bleiben `{display name} · {folder}` ; Bark-Gruppen mit demselben verkürzten Titel. Der Text der Testbenachrichtigung bleibt unverändert. Die API-Eingabe `sender_subject` gibt 400 `config_preview_invalid` zurück. Bei Drittanbieterkanälen werden durch den Wechsel von `subject` zu `off` Absender und Betreff atomar aus allen ausstehenden und fehlgeschlagenen Datensätzen entfernt; Auch spätere Enqueues folgen der hinterlegten Datenschutzerklärung. Native Push zeichnet immer Absender und Betreff auf und behält dabei die Vorschaueinstellung des Drittanbieters bei.

Die Aufbewahrung des Bark-Verlaufs folgt der Speicherverlaufseinstellung der Bark-App sowohl für E-Mail- als auch für Testbenachrichtigungen.

### Webhook-Nutzlast

Der Außenposten sendet einen `POST` mit einem JSON-Body und folgt niemals Weiterleitungen:

```json
{
  "version": 1,
  "id": "3f9c…",
  "test": false,
  "mailbox_id": "mbx_example",
  "account": "Work mailbox",
  "folder": "Clients",
  "sender": "anna@example.org",
  "subject": "Re: Q4 proposal",
  "received_at": "2026-09-28T10:32:00Z",
  "title": "Work mailbox · Clients",
  "message": "Re: Q4 proposal"
}
```

`mailbox_id` ist die stabile Postfach-ID; `account` ist der Anzeigename zum Zeitpunkt der Warteschlangeneinreihung. Gewöhnliche Benachrichtigungen zu Bark, Pushover und Webhook verwenden in allen unterstützten Sprachen den Titel `{display name} · {folder}`. Durch das Umbenennen oder Löschen eines Postfachs bleiben die Identitätsmetadaten bereits in der Warteschlange befindlicher Aufgaben erhalten. Testbenachrichtigungen verwenden separaten Text und lassen Postfachfelder weg.

`sender` und `subject` werden nur in der `subject`-Vorschau angezeigt. `title` und `message` sind lokalisiert und können an ntfy, Gotify und ähnliche Dienste weitergeleitet werden. Der Anzeigename und der Ordner werden auch bei deaktivierter Vorschau gesendet. Wählen Sie ein Label, das für die Weitergabe an Ihren Benachrichtigungsanbieter geeignet ist.

| Kopfzeile              | Bedeutung                                                                                             |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| `X-Mailwake-Event`     | Ereignis-ID, gleich `id`; Bei Wiederholungsversuchen unverändert bleiben, zum Deduplizieren verwenden |
| `X-Mailwake-Timestamp` | Sendezeit in Unix-Sekunden                                                                            |
| `X-Mailwake-Signature` | `sha256=`, gefolgt vom Hex `HMAC-SHA256(secret, "<timestamp>.<raw body>")`                            |

Überprüfen Sie die Signatur mit demselben Geheimnis mithilfe eines Zeitvergleichs und lehnen Sie Zeitstempel ab, die mehr als fünf Minuten entfernt sind:

```python
import hashlib, hmac, time

def verify(secret: bytes, timestamp: str, body: bytes, signature: str) -> bool:
    expected = "sha256=" + hmac.new(secret, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(timestamp)) <= 300 and hmac.compare_digest(expected, signature)
```

Jede 2xx-Antwort gilt als akzeptiert. 429 und 5xx folgen der Wiederholungseinstellung; Andere Status beenden den Versuch und zeichnen einen Fehler auf.

Durch das Speichern der Benachrichtigungseinstellungen werden Felder, Adressen, Kopplungsstatus und Revision validiert, ohne dass ein Test gesendet werden muss. Benutzen Sie nach dem Speichern den expliziten Test-Button. Native Tests nutzen den festen kostenlosen Testendpunkt des Push-Bereitstellungsdienstes und teilen sich das App-Testkontingent; Für normale E-Mail-Benachrichtigungen ist die Berechtigung Native Push erforderlich.