Kontak: route

Run Commands

Satu-satunya titik masuk untuk kontak, list, custom field, dan segmen. Kirim 1 sampai 20 perintah dalam satu request dan dapatkan satu hasil per perintah.

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

Setiap aksi (impor, beri tag, query, berhenti berlangganan, buat list…) adalah perintah yang dikirim ke route ini. Halaman-halaman di bawah ini mendokumentasikan setiap perintah dan argumennya.

i

Error dilaporkan per perintah, dan aksi massal melaporkan per email. Perintah yang gagal tidak menghentikan yang lain, dan status HTTP tetap 200.

Parameter body

  • commandsobject[]wajib

    1 sampai 20 perintah, dijalankan berurutan. Seluruh body bisa berukuran hingga 1 MB.

  • commands[].commandstringwajib

    Nama perintah, misalnya upsert_contacts.

  • commands[].argsobjectopsional

    Argumen perintah. Nilai apa pun bisa berupa $ref ke hasil perintah sebelumnya.

  • commands[].idstringopsional

    Identifier Anda sendiri untuk hasilnya. Default-nya indeks ("0", "1"…). Wajib jika Anda ingin memakai $ref.

Mulai cepat

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

Respons

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

Field respons

  • type

    Selalu SUCCESS jika request-nya sendiri diterima.

  • results[].command

    Perintah yang menghasilkan hasil ini.

  • results[].id

    id yang Anda kirim, atau indeks perintah.

  • results[].type

    SUCCESS atau ERROR.

  • results[].took_ms

    Waktu yang dibutuhkan perintah di dalam server. Sisa waktu request adalah jaringan.

  • results[].data

    Output perintah. Hanya ada jika type bernilai SUCCESS.

  • results[].code / message

    Error-nya. Hanya ada jika type bernilai ERROR.

Autentikasi

Kontak menggunakan API key yang Anda buat di dashboard, di Developers → API Keys. Ini jenis key yang sama dengan yang dipakai untuk mengirim email, dan tidak kedaluwarsa kecuali Anda menetapkan tanggal kedaluwarsa.

  • Authorization

    Kirim Authorization: <api key> atau Authorization: Bearer <api key>.

  • Token mailbox

    Token webmail (S.C.G.…) tidak berfungsi di sini. Token ditolak dengan WRONG_CREDENTIAL_TYPE.

  • IP yang diizinkan

    Jika key memiliki allowlist IP, request dari IP lain mendapat 403 IP_NOT_ALLOWED.

  • Pencabutan

    Key di-cache selama 60 detik, jadi key yang dicabut berhenti berfungsi dalam satu menit. Tanggal kedaluwarsa diperiksa di setiap request.

!

Simpan key di server Anda. Siapa pun yang memilikinya bisa membaca dan mengubah kontak Anda.

Scope

Setiap perintah membutuhkan satu scope pada key. Jika scope tidak ada, hanya perintah itu yang gagal dengan MISSING_SCOPE; sisa request berjalan normal. Key tanpa scope contact:* sama sekali mendapat 403 MISSING_SCOPE sebelum perintah apa pun dijalankan.

  • 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, karena membuat atau memperbarui.

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

Gunakan hasil sebelumnya dengan $ref

Nilai apa pun di dalam args bisa berupa {"$ref": "<id>", "path": "<path>"}. Nilai itu diganti dengan nilai yang ditemukan di path pada hasil perintah dengan id tersebut. Di path, * menelusuri list dan meratakan hasilnya. Request ini menemukan semua kontak di plan pro atau business dan memberi mereka tag, dalam satu kali bolak-balik.

Body request

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

    id dari perintah sebelumnya dalam request yang sama.

  • path

    Path yang dipisahkan garis miring di dalam hasil tersebut. * menelusuri setiap item dalam list.

Aksi massal

Aksi menerima emails (hingga 500) atau email (hanya satu) dan menjawab per email. Email yang salah gagal sendiri, tanpa menghentikan yang lain.

data dari aksi massal

{
  "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 berarti kontak sudah seperti itu, jadi tidak ada yang ditulis. Kirim return_contacts: true untuk mendapatkan kontak lengkap di setiap item.

Minta hanya yang Anda perlukan

Tanpa select, setiap kontak kembali lengkap. Dengan parameter ini, hanya bagian yang Anda sebut yang kembali, dan email selalu kembali. Berlaku di get_contacts, query_contacts, run_segment, dan list_members dengan hydrate. Query yang hanya meminta email dijawab dari indeks dan merupakan pembacaan tercepat.

Body request

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

    email, domain, status, status_reason, status_at, created_at, updated_at, tags, lists, fields, stats, dan field profil (first_name, last_name, phone, company, locale, timezone, source).

  • Bersarang

    fields.<key>, stats.<key>, dan lists.<list_id> hanya mengembalikan bagian itu. Meminta seluruh tingkat atas (fields) mengalahkan sub-key-nya.

Rate limit dan cache

Limit berlaku per IP + API key. Tidak ada antrean: jika melewati batas, request ditolak dengan HTTP 429 dan header Retry-After.

  • 15 request / detik

    Puncak 15. Respons yang disajikan dari cache juga dihitung.

  • 15 bersamaan

    Maksimal 15 request diproses pada saat yang sama.

  • Gunakan batch, bukan loop

    Satu request bisa membawa 20 perintah masing-masing 500 kontak: 10.000 kontak per request.

  • Cache baca: 1,5 dtk

    Pembacaan yang sama (perintah dan args sama) dalam 1,5 detik mengembalikan hasil yang sama, dan pembacaan identik yang sedang berjalan berbagi satu query.

  • Deduplikasi penulisan: 1,5 dtk

    Penulisan yang sama yang diulang dalam 1,5 detik mengembalikan hasil pertama tanpa menulis lagi, jadi klik ganda tidak mengimpor dua kali.

  • Invalidasi cache

    Setiap penulisan langsung membersihkan cache baca Anda, jadi pembacaan berikutnya melihat kondisi terbaru.

Batas

  • Tag

    50 per kontak.

  • List

    75 per kontak.

  • Custom field

    100 per akun.

  • Data custom list

    50 key per list.

  • Teks

    Field text menampung hingga 2.000 karakter. Field profil (first_name…) menampung hingga 256.

Konvensi

Aturan ini berlaku untuk semua perintah.

  • Satu kontak per email

    Kontak adalah milik akun Anda, bukan milik list. List, tag, field, dan status adalah atribut kontak.

  • Email

    Disimpan dalam huruf kecil tanpa spasi. Ana@Acme.com dan ana@acme.com adalah kontak yang sama.

  • Huruf besar/kecil dan aksen

    Tag, opsi enum, dan pencocokan teks mengabaikan huruf besar/kecil dan aksen: "são paulo" cocok dengan "Sao Paulo". Tag disimpan dalam bentuk ternormalisasi.

  • Paginasi

    Daftar yang bisa bertambah mengembalikan has_more dan next_cursor. Kirim next_cursor sebagai cursor di panggilan berikutnya, dengan argumen lain yang sama.

  • Penghapusan

    Menghapus list atau field langsung berlaku; nilainya dihapus dari kontak di latar belakang (purging: true).

Error

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

  • 400INVALID_JSON

    Body bukan {"commands":[...]} atau lebih besar dari 1 MB.

  • 400INVALID_ARGS

    Request tidak memiliki perintah atau lebih dari 20.

  • 401MISSING_AUTH_HEADER

    Tidak ada header Authorization yang dikirim.

  • 401INVALID_API_KEY

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

  • 401API_KEY_EXPIRED

    API key telah melewati tanggal kedaluwarsa yang diatur di dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Token mailbox (S.C.G.…) yang dikirim. Kontak membutuhkan API key dari dashboard.

  • 403IP_NOT_ALLOWED

    Request berasal dari IP yang tidak ada dalam daftar IP yang diizinkan untuk key ini.

  • 403ACCOUNT_BLOCKED

    Akun diblokir.

  • 403MISSING_SCOPE

    Key tidak memiliki scope contact:* sama sekali, jadi tidak ada perintah yang bisa dijalankan. Jika hanya satu scope yang tidak ada, hanya perintah itu yang gagal, dengan HTTP 200.

  • 429RATE_LIMITED

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

  • 503AUTH_UNAVAILABLE

    Autentikasi sementara tidak tersedia. Coba lagi.

  • CMDUNKNOWN_COMMAND

    Nama perintah tidak ada.

  • CMDINTERNAL

    Error server. Detailnya hanya ditulis ke log server.