Kontakte: Kontakte
Kontakte anlegen oder aktualisieren
Legen Sie bis zu 500 Kontakte pro Befehl an oder aktualisieren Sie sie. Nur die gesendeten Teile werden geändert, Sie können dieselbe Datei also gefahrlos erneut importieren.
https://g.sendcorex.com/v1/contactscommand: upsert_contactsErfordert contact:create und contact:update auf Ihrem API Key.
Jeder Kontakt wird einzeln verarbeitet: Eine ungültige E-Mail oder ein ungültiger Feldwert lässt nur diesen Eintrag fehlschlagen. Dieselbe Zeile erneut zu senden schreibt nichts und kommt als changed: false zurück.
Argumente
contactsobject[]erforderlich1 bis 500 Kontakte. Jeder braucht eine
email; alles andere ist optional. Siehe die Kontaktfelder unten.list_idstringoptionalFügt alle Kontakte dieses Befehls angemeldet zu dieser Liste hinzu. Die Liste muss existieren.
z. B.
"customers"tagsstring[]optionalTags, die allen Kontakten dieses Befehls zusätzlich zu den Tags jeder Zeile hinzugefügt werden.
z. B.
["imported"]return_contactsbooleanoptionalFügt jedem Eintrag den vollständigen Kontakt nach der Änderung hinzu.
Schnellstart
import axios from 'axios';
const response = await axios.post(
'https://g.sendcorex.com/v1/contacts',
{
commands: [
{
command: "upsert_contacts",
args: {
list_id: "customers",
tags: [
"imported"
],
contacts: [
{
email: "Ana@Acme.com",
first_name: "Ana",
company: "Acme",
fields: {
plan: "PRO",
age: 31
},
tags: [
"vip"
]
},
{
email: "bob@gmail.com",
first_name: "Bob",
fields: {
age: "22"
},
lists: [
"leads"
]
}
]
}
}
]
},
{ headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);
const [result] = response.data.results;
if (result.type !== 'SUCCESS') throw new Error(`${result.code}: ${result.message}`);
console.log(result.data);Antwort
{
"type": "SUCCESS",
"results": [
{
"command": "upsert_contacts",
"id": "0",
"type": "SUCCESS",
"took_ms": 14,
"data": {
"items": [
{
"id": "Ana@Acme.com",
"ok": true,
"data": {
"created": true,
"changed": true
}
},
{
"id": "bob@gmail.com",
"ok": true,
"data": {
"created": false,
"changed": true
}
}
],
"ok_count": 2,
"failed_count": 0,
"created": 1,
"updated": 1,
"unchanged": 0
}
}
]
}Antwortfelder
items[].idDie E-Mail der Zeile wie gesendet, oder
#<index>, wenn die Zeile keine E-Mail hatte.items[].data.createdtrue, wenn der Kontakt vorher nicht existierte.items[].data.changedfalse, wenn die Zeile dem Gespeicherten entsprach und daher nichts geschrieben wurde.items[].data.contactDer vollständige Kontakt nach der Änderung. Nur mit
return_contacts: true.created / updated / unchangedWie viele Zeilen angelegt, geändert oder bereits aktuell waren.
ok_count / failed_countWie viele Zeilen erfolgreich waren und wie viele fehlgeschlagen sind.
Kontaktfelder
Was jeder Eintrag in contacts enthalten kann. Ein ausgelassener Schlüssel bleibt unverändert; ein als null gesendeter Schlüssel wird geleert.
emailPflicht. Groß-/Kleinschreibung spielt keine Rolle.
first_name, last_name, phone, company, locale, timezone, sourceProfilfelder, je bis zu 256 Zeichen.
nulllöscht den Wert.fields{ key: value }für Ihre benutzerdefinierten Felder. Das Feld muss existieren (siehe Define Field), sonst schlägt der Eintrag fehl.nulllöscht den Wert.tagsWerden zu den aktuellen Tags hinzugefügt. Senden Sie
replace_tags: true, um sie stattdessen zu ersetzen.replace_tagstruemachttagszur vollständigen Tag-Liste des Kontakts.listsListen, denen der Kontakt angemeldet beitritt. Eine nicht existierende Liste lässt den Eintrag mit
NOT_FOUNDfehlschlagen.status / status_reasonGlobaler Status:
subscribed,unsubscribed,bounced,complainedoderblocked.
Lockere Werte werden akzeptiert
Werte benutzerdefinierter Felder werden in den Feldtyp umgewandelt, Sie können also senden, was Ihre CSV liefert.
number31,"31"und"1234,5"funktionieren alle.booltrue,"yes","sim"und"1"gelten als wahr.enum"PRO"wird als"pro"gespeichert. Groß-/Kleinschreibung und Akzente werden beim Abgleich mit den Optionen ignoriert.multi_enum"tech, golf"oder["tech", "golf"].date"2026-10-13"wird als ISO-Datum gespeichert.
Große Importe
Packen Sie bis zu 20 upsert_contacts-Befehle in einen Request: Das sind 10.000 Kontakte pro Request. Halten Sie den Body unter 1 MB und lesen Sie failed_count jedes Ergebnisses, um die zu korrigierenden Zeilen zu finden.
Request-Body
{
"commands": [
{
"command": "upsert_contacts",
"args": {
"list_id": "customers",
"contacts": [
"…rows 1 to 500…"
]
}
},
{
"command": "upsert_contacts",
"args": {
"list_id": "customers",
"contacts": [
"…rows 501 to 1000…"
]
}
}
]
}Sie möchten Kontakte ändern, ohne je einen anzulegen? Verwenden Sie Update Contacts, das dieselben Argumente akzeptiert.
Fehler
Fehler auf HTTP-Ebene liefern type, code und message. Mit CMD markierte Fehler kommen im Befehlsergebnis zurück, mit HTTP 200.
- 401
INVALID_API_KEYDer API Key existiert nicht, wurde widerrufen oder im Dashboard deaktiviert.
- 429
RATE_LIMITEDMehr als 15 Requests/s oder 15 gleichzeitig für dieselbe IP + API Key. Warten Sie die Sekunden aus Retry-After ab.
- CMD
MISSING_SCOPEDem API Key fehlt der Scope, den dieser Befehl braucht. Die anderen Befehle im Request laufen trotzdem.
- CMD
INVALID_ARGSEin Pflichtargument fehlt oder ist ungültig: E-Mail, Feldwert, Enum-Option, where-Schlüssel, Listen-ID …
- CMD
NOT_FOUNDDer Kontakt, die Liste, das Feld oder das Segment existiert nicht.
- CMD
INTERNALServerfehler. Details werden nur ins Server-Log geschrieben.