Bounces & Complaints: Routen

Run Commands

Der einzige Einstiegspunkt für Bounces und Beschwerden. Senden Sie 1 bis 20 Befehle in einem Request und erhalten Sie ein Ergebnis pro Befehl.

POSThttps://g.sendcorex.com/v1/feedback
i

Derselbe Umschlag wie bei Logs und Contacts: Jeder Lesezugriff ist ein Befehl, der an diese Route gesendet wird. Die Seiten darunter dokumentieren jeden Befehl.

i

Fehler werden pro Befehl gemeldet. Ein fehlgeschlagener Befehl stoppt die anderen nicht, und der HTTP-Status bleibt 200.

Body-Parameter

  • commandsobject[]erforderlich

    1 bis 20 Befehle, der Reihe nach ausgeführt. Der gesamte Body darf bis zu 1 MB groß sein.

  • commands[].commandstringerforderlich

    list_feedback oder get_email.

  • commands[].argsobjectoptional

    Die Argumente des Befehls. Jeder Wert kann ein $ref auf das Ergebnis eines früheren Befehls sein.

  • commands[].idstringoptional

    Ihr eigener Bezeichner für das Ergebnis. Standard ist der Index ("0", "1"…). Erforderlich, wenn Sie $ref verwenden möchten.

Schnellstart

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/feedback',
  {
    commands: [
      {
        command: "list_feedback",
        id: "new",
        args: {
          cursor: "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE",
          limit: 100
        }
      },
      {
        command: "get_email",
        id: "one",
        args: {
          email_id: "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30"
        }
      }
    ]
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);

for (const result of response.data.results) {
  if (result.type !== 'SUCCESS') console.error(result.id, result.code, result.message);
  else console.log(result.id, result.data);
}

Antwort

{
  "type": "SUCCESS",
  "results": [
    {
      "command": "list_feedback",
      "id": "new",
      "type": "SUCCESS",
      "took_ms": 12,
      "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"
          }
        ],
        "next_cursor": "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE",
        "has_more": false
      }
    },
    {
      "command": "get_email",
      "id": "one",
      "type": "SUCCESS",
      "took_ms": 4,
      "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"
          }
        ]
      }
    }
  ]
}

Antwortfelder

  • type

    Immer SUCCESS, wenn der Request selbst angenommen wurde.

  • results[].command

    Der Befehl, der dieses Ergebnis erzeugt hat.

  • results[].id

    Die id, die Sie gesendet haben, oder der Index des Befehls.

  • results[].type

    SUCCESS oder ERROR.

  • results[].took_ms

    Zeit, die der Befehl im Server gebraucht hat.

  • results[].data

    Die Ausgabe des Befehls. Nur vorhanden, wenn type SUCCESS ist.

  • results[].code / message

    Der Fehler. Nur vorhanden, wenn type ERROR ist.

Authentifizierung

Verwenden Sie den API key, den Sie im Dashboard unter Developers → API Keys erstellen, mit dem Scope feedback:read.

  • Authorization

    Senden Sie Authorization: <api key> oder Authorization: Bearer <api key>.

  • feedback:read

    Der einzige Scope, den diese Route braucht. Er ist nur lesend.

  • Mailbox-Tokens

    Der Webmail-Token funktioniert hier nicht. Er wird mit WRONG_CREDENTIAL_TYPE abgelehnt.

  • Erlaubte IPs

    Hat der Key eine IP-Allowlist, erhalten Requests von anderen IPs 403 IP_NOT_ALLOWED.

Was im Feed steht

  • Nur, was nicht ankam

    Hard und Soft Bounces, Blockierungen, Spam-Beschwerden und E-Mails, die wir nie gesendet haben. Zugestellte E-Mails stehen nicht hier, sondern in Logs.

  • Ein Ereignis pro E-Mail und Typ

    Lehnt der Server eine E-Mail ab und trifft später eine Bounce-Nachricht dazu ein, erhalten Sie ein Ereignis, nicht zwei. Ebenso bei einem Feedback-Loop-Bericht plus einer Missbrauchsmeldung.

  • Nur endgültige Ergebnisse

    Vorübergehende Zurückstellungen und Wiederholungsversuche erscheinen nie. Ein Soft Bounce wird erst geschrieben, wenn wir aufgeben.

  • 90 Tage

    Ereignisse werden 90 Tage aufbewahrt.

  • Kein Warm-up

    E-Mails aus dem Inbox-Warm-up erscheinen nie.

Rate limits und Cache

Limits gelten pro IP + API key. Wenn Sie darüber liegen, wird der Request mit HTTP 429 und einem Retry-After-Header abgelehnt.

  • 15 Requests / Sekunde

    Spitze von 15. Antworten aus dem Cache zählen ebenfalls.

  • 15 gleichzeitig

    Höchstens 15 Requests werden gleichzeitig verarbeitet.

  • Lese-Cache: 1,5 s

    Derselbe Lesezugriff innerhalb von 1,5 Sekunden liefert dasselbe Ergebnis. Polling alle paar Sekunden ist kein Problem.

Fehler

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

  • 400INVALID_JSON

    Der Body ist nicht {"commands":[...]} oder größer als 1 MB.

  • 400INVALID_ARGS

    Der Request enthält keine Befehle oder mehr als 20.

  • 401MISSING_AUTH_HEADER

    Es wurde kein Authorization-Header gesendet.

  • 401INVALID_API_KEY

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

  • 401API_KEY_EXPIRED

    Der API key hat das im Dashboard festgelegte Ablaufdatum überschritten.

  • 401WRONG_CREDENTIAL_TYPE

    Es wurde ein Mailbox-Token gesendet. Die Feedback API braucht einen API key aus dem Dashboard.

  • 403IP_NOT_ALLOWED

    Der Request kam von einer IP, die nicht zu den erlaubten IPs des Keys gehört.

  • 403ACCOUNT_BLOCKED

    Das Konto ist gesperrt.

  • 403MISSING_SCOPE

    Der Key hat `feedback:read` nicht, daher kann kein Befehl ausgeführt werden.

  • 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.

  • 503AUTH_UNAVAILABLE

    Die Authentifizierung ist vorübergehend nicht verfügbar. Versuchen Sie es erneut.

  • CMDUNKNOWN_COMMAND

    Der Befehlsname existiert nicht.

  • CMDINTERNAL

    Serverfehler. Details werden nur ins Server-Log geschrieben.