Kontak: kontak

Buat atau perbarui kontak

Buat atau perbarui hingga 500 kontak per perintah. Hanya bagian yang Anda kirim yang diubah, jadi aman untuk mengimpor ulang file yang sama.

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

Membutuhkan contact:create dan contact:update pada API key Anda.

i

Setiap kontak diproses sendiri: email atau nilai field yang tidak valid hanya menggagalkan item tersebut. Mengirim baris yang sama lagi tidak menulis apa pun dan kembali sebagai changed: false.

Argumen

  • contactsobject[]wajib

    1 sampai 500 kontak. Masing-masing wajib punya email; selebihnya opsional. Lihat field kontak di bawah.

  • list_idstringopsional

    Menambahkan semua kontak dalam perintah ini ke list ini, dalam status berlangganan. List harus sudah ada.

    mis. "customers"

  • tagsstring[]opsional

    Tag yang ditambahkan ke semua kontak dalam perintah ini, selain tag di masing-masing baris.

    mis. ["imported"]

  • return_contactsbooleanopsional

    Menambahkan kontak lengkap setelah perubahan ke setiap item.

Mulai cepat

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);

Respons

{
  "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
      }
    }
  ]
}

Field respons

  • items[].id

    Email pada baris sesuai yang Anda kirim, atau #<index> jika baris tidak memiliki email.

  • items[].data.created

    true jika kontak sebelumnya belum ada.

  • items[].data.changed

    false jika baris sama dengan yang tersimpan, sehingga tidak ada yang ditulis.

  • items[].data.contact

    Kontak lengkap setelah perubahan. Hanya dengan return_contacts: true.

  • created / updated / unchanged

    Berapa baris yang dibuat, diubah, atau sudah terbaru.

  • ok_count / failed_count

    Berapa baris yang berhasil dan berapa yang gagal.

Field kontak

Isi yang bisa dibawa setiap item contacts. Key yang tidak dikirim tidak diubah; key yang dikirim sebagai null dikosongkan.

  • email

    Wajib. Huruf besar/kecil tidak berpengaruh.

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

    Field profil, masing-masing hingga 256 karakter. null mengosongkan nilainya.

  • fields

    { key: value } untuk custom field Anda. Field harus sudah ada (lihat Define Field), jika tidak item akan gagal. null mengosongkan nilainya.

  • tags

    Ditambahkan ke tag yang ada. Kirim replace_tags: true untuk menggantinya.

  • replace_tags

    true menjadikan tags sebagai daftar tag lengkap kontak.

  • lists

    List yang diikuti, dalam status berlangganan. List yang tidak ada membuat item gagal dengan NOT_FOUND.

  • status / status_reason

    Status global: subscribed, unsubscribed, bounced, complained, atau blocked.

Nilai longgar tetap diterima

Nilai custom field dikonversi ke tipe field, jadi Anda bisa mengirim apa pun yang ada di CSV Anda.

  • number

    31, "31", dan "1234,5" semuanya berfungsi.

  • bool

    true, "yes", "sim", dan "1" bernilai true.

  • enum

    "PRO" disimpan sebagai "pro". Huruf besar/kecil dan aksen diabaikan saat mencocokkan opsi.

  • multi_enum

    "tech, golf" atau ["tech", "golf"].

  • date

    "2026-10-13" disimpan sebagai tanggal ISO.

Impor besar

Masukkan hingga 20 perintah upsert_contacts dalam satu request: itu berarti 10.000 kontak per request. Jaga body di bawah 1 MB, dan baca failed_count dari setiap hasil untuk menemukan baris yang perlu diperbaiki.

Body request

{
  "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

Perlu mengubah kontak tanpa pernah membuat kontak baru? Gunakan Update Contacts, yang menerima argumen yang sama.

Error

Error di level HTTP mengembalikan type, code, dan message. Error yang ditandai CMD dikembalikan di dalam hasil perintah, dengan HTTP 200.

  • 401INVALID_API_KEY

    API key tidak ada, sudah dicabut, atau dinonaktifkan di dashboard.

  • 429RATE_LIMITED

    Lebih dari 15 request/detik atau 15 bersamaan untuk IP + API key yang sama. Tunggu sesuai jumlah detik di Retry-After.

  • CMDMISSING_SCOPE

    API key tidak memiliki scope yang dibutuhkan perintah ini. Perintah lain dalam request tetap berjalan.

  • CMDINVALID_ARGS

    Argumen wajib tidak ada atau tidak valid: email, nilai field, opsi enum, key where, id list…

  • CMDNOT_FOUND

    Kontak, list, field, atau segmen tidak ada.

  • CMDINTERNAL

    Error server. Detailnya hanya ditulis ke log server.