Logs: Routen

Run Commands

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

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

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

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_logs oder get_logs.

  • 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/logs',
  {
    commands: [
      {
        command: "list_logs",
        id: "bounces",
        args: {
          status: "bounced",
          limit: 20
        }
      },
      {
        command: "get_logs",
        id: "one",
        args: {
          id: "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f"
        }
      }
    ]
  },
  { 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_logs",
      "id": "bounces",
      "type": "SUCCESS",
      "took_ms": 21,
      "data": {
        "logs": [
          {
            "id": "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30",
            "to": "old.address@gmail.com",
            "from": "noreply@yourdomain.com",
            "domain": "gmail.com",
            "from_domain": "yourdomain.com",
            "subject": "Your order #1042 has shipped",
            "status": "bounced",
            "status_code": 6,
            "response": "550 5.1.1 The email account that you tried to reach does not exist.",
            "message": null,
            "blocked": false,
            "block_reason": null,
            "retries": 0,
            "tracking_id": "7CK-JDL-Z2M-20261017",
            "sent_at": "2026-10-17T05:58:44.031Z",
            "updated_at": "2026-10-17T05:58:45.600Z"
          }
        ],
        "count": 1,
        "has_more": false,
        "next_cursor": null,
        "partial": false
      }
    },
    {
      "command": "get_logs",
      "id": "one",
      "type": "SUCCESS",
      "took_ms": 9,
      "data": {
        "logs": [
          {
            "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
            "to": "ana@acme.com",
            "from": "noreply@yourdomain.com",
            "domain": "acme.com",
            "from_domain": "yourdomain.com",
            "subject": "Your order #1042 has shipped",
            "status": "delivered",
            "status_code": 2,
            "response": "250 2.0.0 OK 1760684401 a1si123456",
            "message": null,
            "blocked": false,
            "block_reason": null,
            "retries": 0,
            "tracking_id": "7CK-JDL-Y1L-20261017",
            "sent_at": "2026-10-17T06:00:01.204Z",
            "updated_at": "2026-10-17T06:00:02.913Z"
          }
        ],
        "not_found": []
      }
    }
  ]
}

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. Der Rest der Request-Zeit ist Netzwerk.

  • results[].data

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

  • results[].code / message

    Der Fehler. Nur vorhanden, wenn type ERROR ist.

Authentifizierung

Logs verwenden den API key, den Sie im Dashboard unter Developers → API Keys erstellen, mit dem Scope logs:read. Es ist dieselbe Art von Key, mit der Sie E-Mails senden und Kontakte verwalten.

  • Authorization

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

  • logs:read

    Der einzige Scope, den Logs brauchen. Er ist nur lesend: Nichts auf dieser Route ändert Daten.

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

  • Widerruf

    Keys werden 60 Sekunden gecacht, ein widerrufener Key funktioniert also innerhalb einer Minute nicht mehr. Das Ablaufdatum wird bei jedem Request geprüft.

Ein früheres Ergebnis mit $ref verwenden

Jeder Wert in args kann {"$ref": "<id>", "path": "<path>"} sein. Er wird durch den Wert ersetzt, der unter path im Ergebnis des Befehls mit dieser id steht. In path durchläuft * eine Liste. Dieser Request listet die neuesten Bounces und liest deren Bodys, in einem einzigen Roundtrip.

Request-Body

{
  "commands": [
    {
      "command": "list_logs",
      "id": "b",
      "args": {
        "status": "bounced",
        "limit": 10
      }
    },
    {
      "command": "get_logs",
      "args": {
        "ids": {
          "$ref": "b",
          "path": "logs/*/id"
        },
        "include_content": true
      }
    }
  ]
}

Was in den Logs steht

  • Jeder Versand

    Jede E-Mail, die Sie senden, erhält ein Log, das aktualisiert wird, sobald die Zustellung ein Ergebnis hat.

  • 60 Tage

    Logs werden 60 Tage aufbewahrt. Ältere sind weg, und ihre IDs kommen in not_found zurück.

  • Kein Warm-up

    E-Mails aus dem Inbox-Warm-up erscheinen nie, daher liefert Polling nur Ihren echten Traffic.

  • Standardmäßig kein Body

    Listen enthalten nie das HTML. Get Logs liefert es nur mit include_content: true.

Rate limits und Cache

Limits gelten pro IP + API key. Es gibt keine Warteschlange: 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. Viele Seiten parallel abzurufen ist der übliche Weg, dieses Limit zu erreichen: Rufen Sie sie nacheinander ab.

  • Lese-Cache: 1,5 s

    Derselbe Lesezugriff (gleicher Befehl und gleiche Args) innerhalb von 1,5 Sekunden liefert dasselbe Ergebnis, und identische laufende Lesezugriffe teilen sich eine Abfrage. Polling alle paar Sekunden ist kein Problem.

Cursor

List Logs liefert next_cursor, solange es weitere gibt. Er ist opak: Geben Sie ihn unverändert zurück, mit denselben Filtern.

next_cursor

{
  "has_more": true,
  "next_cursor": "MDAwMDAwMDA4MzowOjgyMzkzMTU5OTg3OTU6M2YyYTFi",
  "partial": false
}

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. Logs brauchen 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 `logs: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.