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.
https://g.sendcorex.com/v1/contactsJede Aktion (importieren, taggen, abfragen, abmelden, Liste anlegen …) ist ein Befehl an diese Route. Die Seiten darunter dokumentieren jeden Befehl und seine Argumente.
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[]erforderlich1 bis 20 Befehle, der Reihe nach ausgeführt. Der gesamte Body darf bis zu 1 MB groß sein.
commands[].commandstringerforderlichDer Name des Befehls, zum Beispiel
upsert_contacts.commands[].argsobjectoptionalDie Argumente des Befehls. Jeder Wert kann ein
$refauf das Ergebnis eines früheren Befehls sein.commands[].idstringoptionalIhre eigene Kennung für das Ergebnis. Standard ist der Index (
"0","1"…). Pflicht, wenn Sie$refverwenden 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
typeImmer
SUCCESS, wenn der Request selbst angenommen wurde.results[].commandDer Befehl, der dieses Ergebnis erzeugt hat.
results[].idDie von Ihnen gesendete
idoder der Index des Befehls.results[].typeSUCCESSoderERROR.results[].took_msZeit, die der Befehl im Server benötigt hat. Der Rest der Request-Zeit ist Netzwerk.
results[].dataDie Ausgabe des Befehls. Nur vorhanden, wenn
typeSUCCESSist.results[].code / messageDer Fehler. Nur vorhanden, wenn
typeERRORist.
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.
AuthorizationSenden Sie
Authorization: <api key>oderAuthorization: Bearer <api key>.Mailbox-TokensDas Webmail-Token (
S.C.G.…) funktioniert hier nicht. Es wird mitWRONG_CREDENTIAL_TYPEabgelehnt.Erlaubte IPsHat der Schlüssel eine IP-Allowlist, erhalten Requests von anderen IPs
403 IP_NOT_ALLOWED.WiderrufSchlü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:readget_contacts,query_contacts,count_contacts,list_events,get_stats,list_fields,list_lists,get_list,list_members,list_segments,get_segment,run_segment.contact:createcreate_list,define_field,save_segment.contact:create + updateupsert_contacts, weil es anlegt oder aktualisiert.contact:updateupdate_contacts,add_tags,remove_tags,add_to_lists,remove_from_lists,set_list_subscription,set_status,set_fields,unset_fields,update_list.contact:deletedelete_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"
]
}
}
]
}$refDie
ideines früheren Befehls im selben Request.pathDurch 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
}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 Ebeneemail,domain,status,status_reason,status_at,created_at,updated_at,tags,lists,fields,statsund die Profilfelder (first_name,last_name,phone,company,locale,timezone,source).Verschachteltfields.<key>,stats.<key>undlists.<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 / SekundeSpitze von 15. Aus dem Cache gelieferte Antworten zählen mit.
15 gleichzeitigHöchstens 15 Requests werden gleichzeitig verarbeitet.
Bündeln statt SchleifenEin Request kann 20 Befehle mit je 500 Kontakten enthalten: 10.000 Kontakte pro Request.
Lese-Cache: 1,5 sDerselbe 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 sDerselbe Schreibzugriff innerhalb von 1,5 Sekunden liefert das erste Ergebnis, ohne erneut zu schreiben, ein Doppelklick importiert also nicht doppelt.
Cache-InvalidierungJeder Schreibzugriff leert Ihren Lese-Cache sofort, der nächste Lesezugriff sieht also den neuen Zustand.
Limits
Tags50 pro Kontakt.
Listen75 pro Kontakt.
Benutzerdefinierte Felder100 pro Konto.
Benutzerdefinierte Listendaten50 Schlüssel pro Liste.
TextEin
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-MailEin Kontakt gehört zu Ihrem Konto, nicht zu einer Liste. Listen, Tags, Felder und Status sind Attribute des Kontakts.
E-MailsKleingeschrieben und ohne Leerzeichen gespeichert.
Ana@Acme.comundana@acme.comsind derselbe Kontakt.Groß-/Kleinschreibung und AkzenteTags, Enum-Optionen und Textvergleiche ignorieren Groß-/Kleinschreibung und Akzente:
"são paulo"passt zu"Sao Paulo". Tags werden normalisiert gespeichert.PaginierungListen, die wachsen können, liefern
has_moreundnext_cursor. Senden Sienext_cursorbeim nächsten Aufruf alscursor, mit denselben übrigen Argumenten.LöschungenDas 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.
- 400
INVALID_JSONDer Body ist nicht {"commands":[...]} oder größer als 1 MB.
- 400
INVALID_ARGSDer Request enthält keine Befehle oder mehr als 20.
- 401
MISSING_AUTH_HEADEREs wurde kein Authorization-Header gesendet.
- 401
INVALID_API_KEYDer API Key existiert nicht, wurde widerrufen oder im Dashboard deaktiviert.
- 401
API_KEY_EXPIREDDer API Key hat das im Dashboard festgelegte Ablaufdatum überschritten.
- 401
WRONG_CREDENTIAL_TYPEEs wurde ein Mailbox-Token (S.C.G.…) gesendet. Kontakte brauchen einen API Key aus dem Dashboard.
- 403
IP_NOT_ALLOWEDDer Request kam von einer IP, die nicht zu den erlaubten IPs des Schlüssels gehört.
- 403
ACCOUNT_BLOCKEDDas Konto ist gesperrt.
- 403
MISSING_SCOPEDer 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.
- 429
RATE_LIMITEDMehr als 15 Requests/s oder 15 gleichzeitig für dieselbe IP + API Key. Warten Sie die Sekunden aus Retry-After ab.
- 503
AUTH_UNAVAILABLEDie Authentifizierung ist vorübergehend nicht verfügbar. Versuchen Sie es erneut.
- CMD
UNKNOWN_COMMANDDer Befehlsname existiert nicht.
- CMD
INTERNALServerfehler. Details werden nur ins Server-Log geschrieben.