Tracking Preferences: Routen

Run Commands

Der einzige Einstiegspunkt für Tracking-Präferenzen. Senden Sie 1 bis 20 Befehle in einem Request und erhalten Sie ein Ergebnis pro Befehl.

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

Derselbe Umschlag wie bei Logs, Contacts und Bounces & Complaints. 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

    get_preferences, get_many, get_history, list_changes oder set_preferences.

  • commands[].argsobjectoptional

    Die Argumente des Befehls.

  • commands[].idstringoptional

    Ihr eigener Bezeichner für das Ergebnis. Standard ist der Index ("0", "1"…).

Schnellstart

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/privacy',
  {
    commands: [
      {
        command: "set_preferences",
        id: "set",
        args: {
          email: "jane.doe@example.com",
          track_opens: false
        }
      },
      {
        command: "get_preferences",
        id: "get",
        args: {
          email: "jane.doe@example.com"
        }
      }
    ]
  },
  { 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": "set_preferences",
      "id": "set",
      "type": "SUCCESS",
      "took_ms": 9,
      "data": {
        "changed": true,
        "preference": {
          "email": "jane.doe@example.com",
          "track_opens": false,
          "track_clicks": true,
          "source": "api",
          "updated_at": "2026-10-24T07:20:12.031Z"
        }
      }
    },
    {
      "command": "get_preferences",
      "id": "get",
      "type": "SUCCESS",
      "took_ms": 3,
      "data": {
        "preference": {
          "email": "jane.doe@example.com",
          "track_opens": false,
          "track_clicks": true,
          "source": "api",
          "updated_at": "2026-10-24T07:20:12.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.

  • Authorization

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

  • privacy:read

    Get Preferences, Get Many, Get History und List Changes.

  • privacy:write

    Set Preferences.

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

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. Set Preferences wird nie gecacht.

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. Diese 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 weder `privacy:read` noch `privacy:write`, 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.