Zustellbarkeit und Bounces über API und MCP

Das TrekMail-Dashboard zeigt auf der Registerkarte Statistiken jeder Domain zwei Arten von Bounce-Daten:

1. Eine 30-Tage-Zusammenfassung: Anzahlen für gesendet, zugestellt, Soft Bounces und Hard Bounces sowie Zustell- und Bounce-Raten.
2. Eine Liste pro Empfänger: die letzten 50 ausgehenden Bounces mit SMTP-Statuscode und Antwort des Empfängers, damit Sie erkennen können, warum eine bestimmte Nachricht fehlgeschlagen ist.

Beide sind jetzt über die REST API und den MCP-Server verfügbar. Ein Agent kann Bounce-Gründe abrufen, den Zustand der Reputation zusammenfassen und Abläufe zur Listenpflege unterstützen, ohne das Dashboard zu öffnen.

Verfügbare Daten

Alle drei erfordern domains:read (oder mailboxes:read für die postfachbezogene Liste). Schreibgeschützt. Kein Idempotenzschlüssel erforderlich.

Die API verwendet dieselben Zustellbarkeitsdaten wie die Statistikkarten des Dashboards, sodass beide Ansichten übereinstimmen.

REST API: kurze Beispiele

Domain-Zusammenfassung

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/deliverability?days=30" | jq .

{
  "data": {
    "from": "2026-04-26T00:00:00+00:00",
    "to":   "2026-05-26T23:59:59+00:00",
    "sent": 4180,
    "delivered": 4112,
    "soft_bounce": 22,
    "hard_bounce": 46,
    "forwarding_bounces_excluded": 7,
    "delivery_rate": 0.9837,
    "bounce_rate": 0.0163,
    "status": "good"
  }
}

status ist dasselbe Signal mit drei Zuständen, das im Dashboard dargestellt wird:

• good: Bounce-Rate unter 2 %.
• warning: Bounce-Rate zwischen 2 % und 5 %.
• poor: Bounce-Rate ab 5 %. Prüfen und bereinigen Sie die Versandliste.

forwarding_bounces_excluded gibt an, wie viele weiterleitungsbezogene Bounces aus den Ratenberechnungen entfernt wurden (wie im Dashboard, das diese als Routing-Artefakte und nicht als Probleme der Absenderliste behandelt).

Bounce-Liste pro Empfänger

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/bounces?days=7&type=hard&limit=50" | jq .

{
  "data": [
    {
      "id": 994821,
      "occurred_at": "2026-05-26T18:14:02+00:00",
      "recipient_email": "lost@example.com",
      "event_type": "hard_bounce",
      "smtp_status_code": "550",
      "smtp_response": "5.1.1 The email account that you tried to reach does not exist.",
      "mailbox_id": 7741,
      "domain_id": 123
    }
  ],
  "pagination": { "total": 17, "limit": 50, "offset": 0 }
}

Abfrageparameter

Postfachbezogene Liste

Begrenzen Sie die Abfrage zur Reputationsanalyse einzelner Absender auf ein Postfach:

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/mailboxes/7741/bounces?days=14&type=soft" | jq .

Die Antwort hat dieselbe Struktur wie beim Domain-Endpoint.

Datenschutz bei SMTP-Antworten

TrekMail entfernt interne Diagnoseinformationen, bevor eine SMTP-Antwort zurückgegeben wird. Die verbleibende Nachricht entspricht der Anzeige für den Kontoinhaber im Dashboard. Sie soll bei der Zustellungsdiagnose helfen und keine Serverinterna offenlegen.

MCP-Tools

Alle drei Tools akzeptieren dieselben Parameter wie die REST-Endpoints. Sie sind schreibgeschützt und ändern weder Nachrichten noch Kontoeinstellungen.

get_domain_deliverability

{
  "name": "get_domain_deliverability",
  "arguments": {
    "domain_id": 123,
    "days": 30
  }
}

list_domain_bounces

{
  "name": "list_domain_bounces",
  "arguments": {
    "domain_id": 123,
    "type": "hard",
    "days": 7,
    "limit": 100
  }
}

list_mailbox_bounces

{
  "name": "list_mailbox_bounces",
  "arguments": {
    "mailbox_id": 7741,
    "recipient": "@example.com",
    "limit": 50
  }
}

Zustellbarkeits-Header für Massenversender

Wenn Sie Marketing- oder abonnierte Massenmails senden, können große Postfachanbieter Ein-Klick-Abmelde-Header verlangen. Google wendet diese Regel auf Marketing- und abonnierte Nachrichten von Absendern an, die den Schwellenwert für Massenversand überschreiten; für Transaktionsnachrichten gilt die Ein-Klick-Regel nicht. Es gibt zwei Möglichkeiten, die Header anzuhängen:

Pro Nachricht (gezielt). Übergeben Sie sie im Feld headers von POST /api/v1/messages/send:

{
  "to": ["recipient@example.com"],
  "subject": "...",
  "body": {"text": "..."},
  "headers": {
    "List-Unsubscribe": "<mailto:bounces@mydomain.com?subject=unsubscribe>, <https://mydomain.com/u/abc123>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

Das Feld headers akzeptiert eine kleine Zulassungsliste: List-Unsubscribe, List-Unsubscribe-Post, Reply-To und jeden benutzerdefinierten Tracking-Header X-*. Header-Injection (CR/LF) und verwaltete Header (From, Subject, Date, Message-Id, Authentication-Results, DKIM-Signature usw.) werden mit 422 abgelehnt.

Kontoweit (einmal festlegen). Wenn jede ausgehende Nachricht dieses Kontos automatisiert ist, können Sie auto_list_unsubscribe für das Konto aktivieren. Danach fügt die Plattform jeder ausgehenden Nachricht, die noch keinen entsprechenden Header hat, einen reinen mailto-Header List-Unsubscribe hinzu. List-Unsubscribe-Post wird nicht hinzugefügt, daher ist diese Ausweichlösung keine Ein-Klick-Abmeldung gemäß RFC 8058. Für eine anbieterkompatible Ein-Klick-Abmeldung müssen Sie beide Header pro Nachricht mit Ihrem eigenen HTTPS-Abmelde-Endpoint übergeben, wie im obigen Beispiel. Vom Aufrufer bereitgestellte Header haben immer Vorrang. Die Option ist standardmäßig deaktiviert und vorhandene Konten bleiben unverändert.

Lassen Sie die Option für persönliche Einzelkorrespondenz deaktiviert. Gmail kann bei vorhandenem Header neben dem Absender eine Schaltfläche Abbestellen anzeigen, was für eine Unterhaltung normalerweise unpassend ist.

Muster für KI-Agenten

Diese Endpoints ermöglichen mehrere wertvolle Abläufe:

• Wöchentliche Reputationsübersicht. Rufen Sie jeden Montag get_domain_deliverability für jede Domain des Kontos auf und veröffentlichen Sie eine Zusammenfassung in Slack/Teams. Heben Sie nur Domains hervor, deren status den Wert warning oder poor hat.
• Bounce-gesteuerte Listenpflege. Rufen Sie list_domain_bounces?type=hard&days=14 auf, entfernen Sie Duplikate in recipient_email und sperren Sie diese Adressen anschließend in Ihrer Versandliste. Hard Bounces bedeuten meist, dass die Empfängeradresse nicht mehr existiert; erneutes Senden belastet unnötig die Zustellbarkeit.
• Analyse pro Absender. Wenn die bounce_rate eines Postfachs stark ansteigt, rufen Sie dafür list_mailbox_bounces auf und gruppieren Sie nach smtp_status_code. Viele 550-Codes können auf eine veraltete Adressliste hindeuten; viele 421-Codes können bedeuten, dass der empfangende Mailserver Ihre Rate begrenzt hat.
• Kundensupport-Untersuchung. Wenn ein Benutzer meldet, dass eine E-Mail nicht angekommen ist, lassen Sie den Agenten list_domain_bounces?recipient=<their-address> aufrufen. Die SMTP-Antwort kann den nächsten Schritt anzeigen, etwa ein volles Empfängerpostfach, eine Empfängersperre oder eine DMARC-Ablehnung.

Versionierung

Diese Endpoints folgen demselben Versionierungsvertrag wie die restliche v1-API: nur additive Änderungen und keine inkompatiblen Feldumbenennungen ohne einen v2/-Namespace.

Verwandte Inhalte

• Spam-Metriken: Telemetrie zum Schutz vor eingehendem Spam (get_spam_metrics, get_spam_summary).
• E-Mail-Prüfer: Listenbereinigung vor dem Senden, damit Bounces gar nicht erst entstehen.
• API-Übersicht: Authentifizierung, Scopes, Ratenlimits und Idempotenz.