Kontakte: Routen

Run Commands

Der einzige Einstiegspunkt für Kontakte, Listen, benutzerdefinierte Felder und Segmente. Senden Sie 1 bis 20 Befehle in einem Request und erhalten Sie ein Ergebnis pro Befehl.

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

Jede Aktion (importieren, taggen, abfragen, abmelden, Liste anlegen …) ist ein Befehl an diese Route. Die Seiten darunter dokumentieren jeden Befehl und seine Argumente.

i

Fehler werden pro Befehl gemeldet, Massenaktionen melden pro E-Mail. Ein fehlschlagender 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

    Der Name des Befehls, zum Beispiel upsert_contacts.

  • commands[].argsobjectoptional

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

  • commands[].idstringoptional

    Ihre eigene Kennung für das Ergebnis. Standard ist der Index ("0", "1" …). Pflicht, wenn Sie $ref verwenden möchten.

Schnellstart

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/contacts',
  {
    commands: [
      {
        command: "list_lists"
      },
      {
        command: "get_stats"
      }
    ]
  },
  { 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_lists",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 6,
      "data": {
        "lists": [
          {
            "list_id": "customers",
            "name": "Customers",
            "description": "Everyone who bought at least once",
            "source": "checkout",
            "status": "ready",
            "custom": {
              "origin": "checkout",
              "year": 2026
            },
            "created_at": "2026-10-01T10:00:00.000Z",
            "updated_at": "2026-10-12T15:22:41.000Z",
            "stats": {
              "total": 1834,
              "ok": 1790,
              "opened": 912,
              "clicked": 233
            }
          }
        ]
      }
    },
    {
      "command": "get_stats",
      "id": "1",
      "type": "SUCCESS",
      "took_ms": 9,
      "data": {
        "total": 2040,
        "status": {
          "subscribed": 1951,
          "unsubscribed": 61,
          "bounced": 22,
          "complained": 3,
          "blocked": 3
        },
        "lists": {
          "customers": {
            "total": 1834,
            "ok": 1790,
            "opened": 912,
            "clicked": 233
          }
        },
        "tags": {
          "customer": 1834,
          "vip": 120
        }
      }
    }
  ]
}

Antwortfelder

  • type

    Immer SUCCESS, wenn der Request selbst angenommen wurde.

  • results[].command

    Der Befehl, der dieses Ergebnis erzeugt hat.

  • results[].id

    Die von Ihnen gesendete id oder der Index des Befehls.

  • results[].type

    SUCCESS oder ERROR.

  • results[].took_ms

    Zeit, die der Befehl im Server benötigt 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

Kontakte verwenden den API Key, den Sie im Dashboard unter Developers → API Keys erstellen. Es ist dieselbe Art Schlüssel wie für den E-Mail-Versand, und er läuft nicht ab, sofern Sie kein Ablaufdatum festlegen.

  • Authorization

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

  • Mailbox-Tokens

    Das Webmail-Token (S.C.G.…) funktioniert hier nicht. Es wird mit WRONG_CREDENTIAL_TYPE abgelehnt.

  • Erlaubte IPs

    Hat der Schlüssel eine IP-Allowlist, erhalten Requests von anderen IPs 403 IP_NOT_ALLOWED.

  • Widerruf

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

!

Bewahren Sie den Schlüssel auf Ihrem Server auf. Jeder, der ihn hat, kann Ihre Kontakte lesen und ändern.

Scopes

Jeder Befehl braucht einen Scope auf dem Schlüssel. Fehlt ein Scope, schlägt nur dieser Befehl mit MISSING_SCOPE fehl; der Rest des Requests läuft normal. Ein Schlüssel ganz ohne contact:*-Scope erhält 403 MISSING_SCOPE, bevor irgendein Befehl läuft.

  • contact:read

    get_contacts, query_contacts, count_contacts, list_events, get_stats, list_fields, list_lists, get_list, list_members, list_segments, get_segment, run_segment.

  • contact:create

    create_list, define_field, save_segment.

  • contact:create + update

    upsert_contacts, weil es anlegt oder aktualisiert.

  • contact:update

    update_contacts, add_tags, remove_tags, add_to_lists, remove_from_lists, set_list_subscription, set_status, set_fields, unset_fields, update_list.

  • contact:delete

    delete_contacts, delete_list, delete_field, delete_segment.

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 und flacht das Ergebnis ab. Dieser Request findet alle Kontakte im Plan pro oder business und taggt sie, in einem einzigen Roundtrip.

Request-Body

{
  "commands": [
    {
      "command": "query_contacts",
      "id": "q",
      "args": {
        "where": {
          "fields": {
            "plan": {
              "in": [
                "pro",
                "business"
              ]
            }
          }
        },
        "select": [
          "email"
        ]
      }
    },
    {
      "command": "add_tags",
      "args": {
        "emails": {
          "$ref": "q",
          "path": "contacts/*/email"
        },
        "tags": [
          "premium"
        ]
      }
    }
  ]
}
  • $ref

    Die id eines früheren Befehls im selben Request.

  • path

    Durch Schrägstriche getrennter Pfad in dieses Ergebnis. * durchläuft jedes Element einer Liste.

Massenaktionen

Aktionen nehmen emails (bis zu 500) oder email (nur eine) und antworten E-Mail für E-Mail. Eine fehlerhafte E-Mail schlägt allein fehl, ohne die anderen zu stoppen.

data einer Massenaktion

{
  "items": [
    {
      "id": "ana@acme.com",
      "ok": true,
      "data": {
        "changed": true
      }
    },
    {
      "id": "x@y.com",
      "ok": false,
      "code": "NOT_FOUND",
      "message": "contact not found"
    }
  ],
  "ok_count": 1,
  "failed_count": 1
}
i

changed: false bedeutet, dass der Kontakt schon so war und nichts geschrieben wurde. Senden Sie return_contacts: true, um in jedem Eintrag den vollständigen Kontakt zu erhalten.

Fragen Sie nur ab, was Sie brauchen

Ohne select kommt jeder Kontakt vollständig zurück. Damit nur die genannten Teile, und email immer. Funktioniert bei get_contacts, query_contacts, run_segment und list_members mit hydrate. Eine reine E-Mail-Abfrage wird aus dem Index beantwortet und ist der schnellste Lesezugriff überhaupt.

Request-Body

{
  "commands": [
    {
      "command": "query_contacts",
      "args": {
        "where": {
          "list": "customers",
          "sendable": true
        },
        "select": [
          "first_name",
          "status",
          "fields.plan",
          "stats.open_count"
        ]
      }
    }
  ]
}
  • Oberste Ebene

    email, domain, status, status_reason, status_at, created_at, updated_at, tags, lists, fields, stats und die Profilfelder (first_name, last_name, phone, company, locale, timezone, source).

  • Verschachtelt

    fields.<key>, stats.<key> und lists.<list_id> liefern nur diesen Teil. Die Anfrage nach der ganzen obersten Ebene (fields) hat Vorrang vor ihren Unterschlüsseln.

Rate Limits und Cache

Die Limits gelten pro IP + API Key. Es gibt keine Warteschlange: Bei Überschreitung wird der Request mit HTTP 429 und einem Retry-After-Header abgelehnt.

  • 15 Requests / Sekunde

    Spitze von 15. Aus dem Cache gelieferte Antworten zählen mit.

  • 15 gleichzeitig

    Höchstens 15 Requests werden gleichzeitig verarbeitet.

  • Bündeln statt Schleifen

    Ein Request kann 20 Befehle mit je 500 Kontakten enthalten: 10.000 Kontakte pro Request.

  • Lese-Cache: 1,5 s

    Derselbe Lesezugriff (gleicher Befehl und gleiche Args) innerhalb von 1,5 Sekunden liefert dasselbe Ergebnis, und identische gleichzeitige Lesezugriffe teilen sich eine Abfrage.

  • Schreib-Deduplizierung: 1,5 s

    Derselbe Schreibzugriff innerhalb von 1,5 Sekunden liefert das erste Ergebnis, ohne erneut zu schreiben, ein Doppelklick importiert also nicht doppelt.

  • Cache-Invalidierung

    Jeder Schreibzugriff leert Ihren Lese-Cache sofort, der nächste Lesezugriff sieht also den neuen Zustand.

Limits

  • Tags

    50 pro Kontakt.

  • Listen

    75 pro Kontakt.

  • Benutzerdefinierte Felder

    100 pro Konto.

  • Benutzerdefinierte Listendaten

    50 Schlüssel pro Liste.

  • Text

    Ein text-Feld fasst bis zu 2.000 Zeichen. Profilfelder (first_name …) fassen bis zu 256.

Konventionen

Diese Regeln gelten für alle Befehle.

  • Ein Kontakt pro E-Mail

    Ein Kontakt gehört zu Ihrem Konto, nicht zu einer Liste. Listen, Tags, Felder und Status sind Attribute des Kontakts.

  • E-Mails

    Kleingeschrieben und ohne Leerzeichen gespeichert. Ana@Acme.com und ana@acme.com sind derselbe Kontakt.

  • Groß-/Kleinschreibung und Akzente

    Tags, Enum-Optionen und Textvergleiche ignorieren Groß-/Kleinschreibung und Akzente: "são paulo" passt zu "Sao Paulo". Tags werden normalisiert gespeichert.

  • Paginierung

    Listen, die wachsen können, liefern has_more und next_cursor. Senden Sie next_cursor beim nächsten Aufruf als cursor, mit denselben übrigen Argumenten.

  • Löschungen

    Das Löschen einer Liste oder eines Felds wirkt sofort; die Werte werden im Hintergrund aus den Kontakten entfernt (purging: true).

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 (S.C.G.…) gesendet. Kontakte brauchen einen API Key aus dem Dashboard.

  • 403IP_NOT_ALLOWED

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

  • 403ACCOUNT_BLOCKED

    Das Konto ist gesperrt.

  • 403MISSING_SCOPE

    Der Schlüssel hat überhaupt keinen contact:*-Scope, daher kann kein Befehl laufen. Fehlt nur ein Scope, schlägt nur dieser Befehl fehl, mit HTTP 200.

  • 429RATE_LIMITED

    Mehr als 15 Requests/s oder 15 gleichzeitig für dieselbe IP + API Key. Warten Sie die 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.