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.

POSThttps://g.sendcorex.com/v1/contactscommand: upsert_contacts
i

Erfordert contact:create und contact:update auf Ihrem API Key.

i

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[]erforderlich

    1 bis 500 Kontakte. Jeder braucht eine email; alles andere ist optional. Siehe die Kontaktfelder unten.

  • list_idstringoptional

    Fügt alle Kontakte dieses Befehls angemeldet zu dieser Liste hinzu. Die Liste muss existieren.

    z. B. "customers"

  • tagsstring[]optional

    Tags, die allen Kontakten dieses Befehls zusätzlich zu den Tags jeder Zeile hinzugefügt werden.

    z. B. ["imported"]

  • return_contactsbooleanoptional

    Fü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[].id

    Die E-Mail der Zeile wie gesendet, oder #<index>, wenn die Zeile keine E-Mail hatte.

  • items[].data.created

    true, wenn der Kontakt vorher nicht existierte.

  • items[].data.changed

    false, wenn die Zeile dem Gespeicherten entsprach und daher nichts geschrieben wurde.

  • items[].data.contact

    Der vollständige Kontakt nach der Änderung. Nur mit return_contacts: true.

  • created / updated / unchanged

    Wie viele Zeilen angelegt, geändert oder bereits aktuell waren.

  • ok_count / failed_count

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

  • email

    Pflicht. Groß-/Kleinschreibung spielt keine Rolle.

  • first_name, last_name, phone, company, locale, timezone, source

    Profilfelder, je bis zu 256 Zeichen. null löscht den Wert.

  • fields

    { key: value } für Ihre benutzerdefinierten Felder. Das Feld muss existieren (siehe Define Field), sonst schlägt der Eintrag fehl. null löscht den Wert.

  • tags

    Werden zu den aktuellen Tags hinzugefügt. Senden Sie replace_tags: true, um sie stattdessen zu ersetzen.

  • replace_tags

    true macht tags zur vollständigen Tag-Liste des Kontakts.

  • lists

    Listen, denen der Kontakt angemeldet beitritt. Eine nicht existierende Liste lässt den Eintrag mit NOT_FOUND fehlschlagen.

  • status / status_reason

    Globaler Status: subscribed, unsubscribed, bounced, complained oder blocked.

Lockere Werte werden akzeptiert

Werte benutzerdefinierter Felder werden in den Feldtyp umgewandelt, Sie können also senden, was Ihre CSV liefert.

  • number

    31, "31" und "1234,5" funktionieren alle.

  • bool

    true, "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…"
        ]
      }
    }
  ]
}
i

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.

  • 401INVALID_API_KEY

    Der API Key existiert nicht, wurde widerrufen oder im Dashboard deaktiviert.

  • 429RATE_LIMITED

    Mehr als 15 Requests/s oder 15 gleichzeitig für dieselbe IP + API Key. Warten Sie die Sekunden aus Retry-After ab.

  • CMDMISSING_SCOPE

    Dem API Key fehlt der Scope, den dieser Befehl braucht. Die anderen Befehle im Request laufen trotzdem.

  • CMDINVALID_ARGS

    Ein Pflichtargument fehlt oder ist ungültig: E-Mail, Feldwert, Enum-Option, where-Schlüssel, Listen-ID …

  • CMDNOT_FOUND

    Der Kontakt, die Liste, das Feld oder das Segment existiert nicht.

  • CMDINTERNAL

    Serverfehler. Details werden nur ins Server-Log geschrieben.