Eingehende Abmelde-Mail-Verarbeitung

Verwandeln Sie den mailto-basierten "Abmelden"-Button in Posteingangs-Clients (Apple Mail, Outlook, Gmail) in automatisierte Opt-outs, indem Sie Antworten an das AI Visibility Tool weiterleiten.

TL;DR

Jede Produkt-E-Mail enthält einen List-Unsubscribe-Header mit einem mailto: Ziel (z. B. support@visibility-tool.com mit dem Betreff "unsubscribe-onboarding"). Um diese Antworten zu berücksichtigen, müssen Sie dieses Postfach einlesen: entweder über einen eingehenden Parse-Webhook (SendGrid / Mailgun / Postmark), der auf /api/v1/inbound/unsubscribe zeigt, oder über den optionalen IMAP-Poller. Beide speisen denselben Handler.

Zwei Eingangswege

  1. Eingehender HTTP-Webhook — POST /api/v1/inbound/unsubscribe. Die meisten verwalteten Eingangs-Parse-Anbieter (SendGrid Inbound Parse, Mailgun Routes, Postmark Inbound, Cloudflare Email Workers) können geparste Nachrichten als JSON oder multipart/form-data weiterleiten. Der Endpunkt ist mit einem gemeinsamen Geheimnis authentifiziert.
  2. IMAP-Abfrage — Ein APScheduler-Job verbindet sich mit einem echten Postfach, das Sie kontrollieren, liest ungelesene Nachrichten, deren Betreff mit beginnt unsubscribe-, verarbeitet sie und markiert sie als gesehen. Nur aktiviert, wenn die IMAP-Umgebungsvariablen gesetzt sind.

Erforderliche Umgebungsvariablen

Webhook (beliebiger eingehender Parser)
  • INBOUND_UNSUBSCRIBE_SECRET — Gemeinsames Geheimnis, das der Parser bei jedem Aufruf vorlegen muss. Wenn nicht gesetzt, gibt der Endpunkt 503 zurück und die eingehende Verarbeitung ist deaktiviert. Generieren Sie eine lange zufällige Zeichenfolge, z. B. openssl rand -hex 32.
IMAP-Poller (optional, nur wenn Sie keinen Webhook verwenden können)
  • UNSUBSCRIBE_IMAP_HOST — IMAP-Server-Hostname. Das Setzen dieser Option aktiviert den Poller.
  • UNSUBSCRIBE_IMAP_PORT — Standard 993
  • UNSUBSCRIBE_IMAP_USER — Postfach-Login
  • UNSUBSCRIBE_IMAP_PASSWORD — Postfach-Passwort oder App-Passwort
  • UNSUBSCRIBE_IMAP_FOLDER — Standard INBOX
  • UNSUBSCRIBE_IMAP_SSL — 1 (Standard) für IMAPS, auf gesetzt auf 0 nur wenn du wirklich Klartext benötigst
  • UNSUBSCRIBE_IMAP_INTERVAL_MINUTES — Abfrageintervall in Minuten, Standard 10

Beispiel: SendGrid Inbound Parse

  1. Gehe in SendGrid zu Einstellungen → Inbound Parse und füge einen Host hinzu (z.B. unsubscribe.visibility-tool.com) mit dem MX-Eintrag, den die Seite dir sagt, zu erstellen.
  2. Setze die Ziel-URL auf:
    https://ai.visibility-tool.com/api/v1/inbound/unsubscribe?secret=YOUR_SECRET
    (oder, vorzugsweise, lasse die URL sauber und konfiguriere SendGrid, um das Geheimnis im X-Inbound-Secret Header zu senden, wenn dein Anbieter benutzerdefinierte Header unterstützt).
  3. Lass "POST die rohe, vollständige MIME-Nachricht" deaktiviert. SendGrid sendet dann ein multipart/form-data-Payload mit subject, text, fromFeldern, die der Endpunkt sofort versteht.
  4. Leite das Abmelde-Alias an deinen Mail-Anbieter (z.B. support@visibility-tool.comoder ein dediziertes unsubscribe@…Alias) an den Parse-Host weiter.
  5. Sende eine Test-E-Mail mit dem Betreff unsubscribe-onboarding und einem gültigen Token im Body. Ein erfolgreicher Aufruf gibt HTTP 200 mit {"status": "done"}.

Mailgun-Routen und Postmark Inbound funktionieren auf die gleiche Weise — sie posten JSON- oder formcodierte Payloads mit subject / body-plain / sender (Mailgun) oder Subject / TextBody / From (Postmark) und der Endpunkt verarbeitet alle drei Formen.

Beispiel: IMAP Poller

Wenn ein verwalteter Inbound-Parser keine Option ist, weise die App auf ein echtes Postfach. Setze die Umgebungsvariablen unten, starte die App neu, und der Scheduler registriert automatisch einen Polling-Job:

UNSUBSCRIBE_IMAP_HOST=imap.gmail.com
UNSUBSCRIBE_IMAP_PORT=993
UNSUBSCRIBE_IMAP_USER=unsubscribe@visibility-tool.com
UNSUBSCRIBE_IMAP_PASSWORD=********
UNSUBSCRIBE_IMAP_FOLDER=INBOX
UNSUBSCRIBE_IMAP_SSL=1
UNSUBSCRIBE_IMAP_INTERVAL_MINUTES=10

Beim Start solltest du sehen IMAP unsubscribe poller ENABLED (every 10 min) in den Anwendungsprotokollen. Jeder Zyklus liest bis zu 50 ungelesene unsubscribe-* Nachrichten, die die Absender abmelden und die Nachrichten als Gesehen markieren, damit sie nicht zweimal verarbeitet werden.

Funktionsweise überprüfen

  • Sende dir selbst eine Produkt-E-Mail und klicke dann auf "Abmelden" in deinem Posteingangsclient. Die Antwort sollte innerhalb von Sekunden (Webhook) oder einem Polling-Zyklus (IMAP) abgemeldet werden.
  • Prüfe /ai-visibility/admin/activity-log und nach Kategorie filtern systemErfolgreiche Abmeldungen werden protokolliert als email_unsubscribed mit source: email_mailto. Ungültige Tokens oder unbekannte Konten werden protokolliert als email_unsubscribe_failed.
  • Antworten mit einem fehlerhaften oder fehlenden Token werden akzeptiert, protokolliert und stillschweigend ignoriert – nichts wird an den Absender zurückgeschickt.
Gut zu wissen
  • Du benötigst nur einen der beiden Pfade. Wähle den Webhook, wenn dein transaktionaler Absender bereits eingehende Parsing-Funktionen anbietet – er ist schneller und benötigt kein Postfach zur Überwachung.
  • Beide Pfade teilen sich denselben Handler, sodass Abmeldungen immer in der richtigen Kategoriepräferenz (Onboarding, Rechnungsbenachrichtigungen, wöchentlicher Überblick, Produktbenachrichtigungen) basierend auf dem signierten Token im Antworttext landen.
  • Bevorzuge es, das Geheimnis in einem Header zu senden (X-Inbound-Secret oder Authorization: Bearer …). Abfragezeichenfolgen-Geheimnisse funktionieren als Fallback, können jedoch in Proxy- und Zugriffsprotokolle gelangen.
← Zurück zur Dokumentation