Bounces & Complaints: Lesen

Feedback auflisten

Jeder Bounce, jede Blockierung und jede Beschwerde Ihres Kontos, älteste zuerst, damit Sie mit einem Cursor pollen können und keine verpassen.

POSThttps://g.sendcorex.com/v1/feedbackcommand: list_feedback
i

Erfordert den Scope feedback:read für Ihren API key.

i

Behalten Sie next_cursor und senden Sie ihn beim nächsten Aufruf. Er kommt immer zurück, auch wenn es nichts Neues gab, sodass Ihre Schleife eine leere Seite nie als Sonderfall behandeln muss.

i

Ereignisse erscheinen etwa 10 Sekunden, nachdem sie passiert sind. Diese kleine Verzögerung garantiert, dass zwischen zwei Abfragen nichts übersprungen wird.

Argumente

  • cursorstringoptional

    Der next_cursor des vorherigen Aufrufs. Beim ersten Mal ohne ihn (oder mit since) beginnen.

    z. B. "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE"

  • sincestringoptional

    RFC 3339. Wo Sie beginnen, wenn Sie noch keinen Cursor haben. Wird ignoriert, wenn cursor gesendet wird. Ohne beides beginnen Sie am Anfang der 90 Tage.

    z. B. "2026-10-01T00:00:00Z"

  • kindsstring[]optional

    Nur diese Typen: bounce_hard, bounce_soft, blocked, complaint, dropped. Ein kommagetrennter String funktioniert auch. Ohne Angabe erhalten Sie alle.

    z. B. ["bounce_hard", "complaint"]

  • limitnumberoptional

    Ereignisse pro Aufruf, von 1 bis 1000. Standard: 100.

    z. B. 100

Schnellstart

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/feedback',
  {
    commands: [
      {
        command: "list_feedback",
        args: {
          cursor: "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE",
          kinds: [
            "bounce_hard",
            "complaint"
          ],
          limit: 100
        }
      }
    ]
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);

const [result] = response.data.results;
if (result.type !== 'SUCCESS') throw new Error(`${result.code}: ${result.message}`);
console.log(result.data);

Antwort

{
  "type": "SUCCESS",
  "results": [
    {
      "command": "list_feedback",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 18,
      "data": {
        "events": [
          {
            "email_id": "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30",
            "kind": "bounce_hard",
            "source": "smtp",
            "recipient": "old.address@gmail.com",
            "from": "noreply@yourdomain.com",
            "smtp_code": 550,
            "enhanced_code": "5.1.1",
            "diagnostic": "550-5.1.1 The email account that you tried to reach does not exist.",
            "at": "2026-10-17T05:58:44.031Z"
          },
          {
            "email_id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
            "kind": "complaint",
            "source": "fbl_microsoft",
            "recipient": "ana@outlook.com",
            "from": "news@yourdomain.com",
            "campaign_id": "c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
            "reporting_mta": "staff@hotmail.com",
            "at": "2026-10-17T09:12:03.500Z"
          },
          {
            "email_id": "5a6b7c8d-1e2f-4a3b-9c4d-5e6f7a8b9c0d",
            "kind": "blocked",
            "source": "smtp",
            "recipient": "paulo@corp-example.com",
            "from": "noreply@yourdomain.com",
            "smtp_code": 554,
            "enhanced_code": "5.7.1",
            "diagnostic": "554 5.7.1 Service unavailable; client host blocked using zen.spamhaus.org",
            "at": "2026-10-17T10:40:19.002Z"
          }
        ],
        "next_cursor": "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE",
        "has_more": false
      }
    }
  ]
}

Antwortfelder

  • events

    Die Ereignisse dieses Aufrufs, älteste zuerst. Jedes hat die unten stehenden Felder.

  • next_cursor

    Senden Sie ihn beim nächsten Aufruf als cursor. Wenn nichts Neues kam, ist es derselbe Cursor, den Sie gesendet haben.

  • has_more

    true, wenn bereits weitere Ereignisse warten: Rufen Sie sofort erneut auf, statt auf Ihre nächste Abfrage zu warten.

  • events[].email_id

    Die E-Mail-ID (eine UUID): die id, die Sie beim Senden erhalten haben, und dieselbe ID wie in Logs und Webhooks.

  • events[].kind

    Was passiert ist: bounce_hard, bounce_soft, blocked, complaint oder dropped. Siehe Typen unten.

  • events[].source

    Woher wir es wissen: die SMTP-Antwort, eine Bounce-Nachricht, ein Feedback Loop, eine Missbrauchsmeldung… Siehe Quellen unten.

  • events[].recipient

    Die Adresse, an die die E-Mail gesendet wurde.

  • events[].from

    Die Absenderadresse.

  • events[].campaign_id

    Die Kampagne, falls die E-Mail zu einer gehört.

  • events[].smtp_code / events[].enhanced_code

    Der Code, den der Empfängerserver geantwortet hat, zum Beispiel 550 und 5.1.1. Nur bei Bounces und Blockierungen.

  • events[].diagnostic

    Die vollständige Antwort des Empfängerservers oder der in einer Missbrauchsmeldung genannte Grund.

  • events[].reporting_mta

    Wer es gemeldet hat: der Server, der die Bounce-Nachricht gesendet hat, die Feedback-Loop-Adresse oder web für die Meldeseite.

  • events[].at

    Wann es passiert ist. ISO 8601, UTC.

Typen

  • bounce_hard

    Die Adresse existiert nicht oder nimmt keine E-Mails mehr an (5.1.x, die meisten 5xx). Entfernen Sie sie aus Ihren Listen: Erneutes Senden schadet Ihrer Reputation.

  • bounce_soft

    Ein vorübergehendes Problem, das sich nicht rechtzeitig gelöst hat: Postfach voll (5.2.2), ein 4xx ohne verbleibende Versuche oder die E-Mail ist in der Warteschlange abgelaufen. Sie können es später erneut versuchen.

  • blocked

    Der Empfängerserver hat die Nachricht selbst abgelehnt: Spamfilter, Richtlinie, Blocklist oder Authentifizierung (5.7.x). Die Adresse ist in Ordnung, entfernen Sie sie also nicht: Korrigieren Sie, was gesendet wurde.

  • complaint

    Der Empfänger hat die E-Mail als Spam markiert (Feedback Loop) oder als Missbrauch gemeldet. Senden Sie nicht mehr an diese Adresse.

  • dropped

    Sendcorex hat sie nie gesendet: Konto gesperrt, keine Credits oder ungültige Adresse.

Quellen

  • smtp

    Die Antwort des Empfängerservers während der Zustellung.

  • dsn

    Eine Bounce-Nachricht, die später am Return-Path eintraf, nachdem der Server die E-Mail zunächst angenommen hatte.

  • expired

    Die E-Mail war nach 5 Tagen noch in der Warteschlange und wurde aufgegeben.

  • retries_exhausted

    Der Empfängerserver hat sie immer wieder zurückgestellt, und alle Wiederholungsversuche wurden verbraucht.

  • outgoing

    Vor dem Senden gestoppt (das tragen dropped-Ereignisse).

  • fbl_microsoft / fbl_yahoo / fbl_other

    Eine Spam-Meldung aus dem Feedback Loop des Anbieters (Outlook/Hotmail, Yahoo/AOL, andere).

  • abuse_mailbox

    Jemand hat an die Missbrauchsadresse im X-Report-Abuse-Header der E-Mail geschrieben.

  • abuse_web

    Jemand hat die im X-Report-Abuse-Header verlinkte Meldeseite verwendet.

Polling

Speichern Sie den Cursor an einem Ort, der einen Neustart übersteht (eine Datenbankzeile, eine Datei). Lesen Sie bei jedem Durchlauf, bis has_more false ist, verarbeiten Sie jedes Ereignis und speichern Sie den neuen Cursor.

Node.js

let cursor = await loadCursor(); // null the first time

async function poll() {
  let more = true;
  while (more) {
    const [result] = await call({
      command: 'list_feedback',
      args: cursor ? { cursor, limit: 500 } : { since: new Date(Date.now() - 86400_000).toISOString(), limit: 500 },
    });
    for (const e of result.data.events) {
      if (e.kind === 'bounce_hard' || e.kind === 'complaint') await suppress(e.recipient, e.kind); // your code
    }
    cursor = result.data.next_cursor;
    await saveCursor(cursor);
    more = result.data.has_more;
  }
}

setInterval(poll, 30_000);
i

call ist ein beliebiger Helper, der { commands: [...] } per POST an /v1/feedback sendet und results zurückgibt, wie in Run Commands.

!

Entfernen Sie Adressen nur bei bounce_hard und complaint. Ein blocked-Ereignis bedeutet, dass der Server diese Nachricht abgelehnt hat, nicht dass die Adresse schlecht ist.

i

Lieber Push? Die Webhooks bounced und fbl_complaint liefern dieselben Ereignisse in dem Moment, in dem sie passieren. Polling ist das Sicherheitsnetz, wenn Ihr Endpoint nicht erreichbar war.

Nach Typ filtern

Mit kinds bewegt sich der Cursor trotzdem über die herausgefilterten Ereignisse hinweg, sodass eine gefilterte Schleife genauso günstig ist wie eine ungefilterte.

Request-Body

{
  "commands": [
    {
      "command": "list_feedback",
      "args": {
        "since": "2026-10-01T00:00:00Z",
        "kinds": [
          "complaint"
        ]
      }
    }
  ]
}

Das Ereignis

Ereignis

{
  "email_id": "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30",
  "kind": "bounce_hard",
  "source": "smtp",
  "recipient": "old.address@gmail.com",
  "from": "noreply@yourdomain.com",
  "smtp_code": 550,
  "enhanced_code": "5.1.1",
  "diagnostic": "550-5.1.1 The email account that you tried to reach does not exist.",
  "at": "2026-10-17T05:58:44.031Z"
}

Fehler

Fehler auf HTTP-Ebene liefern type, code und message. Mit CMD markierte Fehler kommen im Befehlsergebnis zurück, mit HTTP 200.

  • 401INVALID_API_KEY

    Der API key existiert nicht, wurde widerrufen oder im Dashboard deaktiviert.

  • 429RATE_LIMITED

    Mehr als 15 Requests/s oder 15 gleichzeitig für dieselbe IP + API key. Warten Sie die Anzahl Sekunden aus Retry-After ab.

  • CMDMISSING_SCOPE

    Der API key hat `feedback:read` nicht.

  • CMDINVALID_ARGS

    Ein Argument ist ungültig: unbekannter Typ, `since` nicht im Format RFC 3339, limit außerhalb des Bereichs, fehlende `email_id`…

  • CMDINVALID_CURSOR

    Der Cursor ist fehlerhaft oder stammt aus einem anderen Konto. Beginnen Sie ohne Cursor (oder mit `since`) neu.

  • CMDINTERNAL

    Serverfehler. Details werden nur ins Server-Log geschrieben.