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.
https://g.sendcorex.com/v1/contactsSetiap 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.
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[]wajib1 sampai 20 perintah, dijalankan berurutan. Seluruh body bisa berukuran hingga 1 MB.
commands[].commandstringwajibNama perintah, misalnya
upsert_contacts.commands[].argsobjectopsionalArgumen perintah. Nilai apa pun bisa berupa
$refke hasil perintah sebelumnya.commands[].idstringopsionalIdentifier 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
typeSelalu
SUCCESSjika request-nya sendiri diterima.results[].commandPerintah yang menghasilkan hasil ini.
results[].ididyang Anda kirim, atau indeks perintah.results[].typeSUCCESSatauERROR.results[].took_msWaktu yang dibutuhkan perintah di dalam server. Sisa waktu request adalah jaringan.
results[].dataOutput perintah. Hanya ada jika
typebernilaiSUCCESS.results[].code / messageError-nya. Hanya ada jika
typebernilaiERROR.
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.
AuthorizationKirim
Authorization: <api key>atauAuthorization: Bearer <api key>.Token mailboxToken webmail (
S.C.G.…) tidak berfungsi di sini. Token ditolak denganWRONG_CREDENTIAL_TYPE.IP yang diizinkanJika key memiliki allowlist IP, request dari IP lain mendapat
403 IP_NOT_ALLOWED.PencabutanKey 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: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, karena membuat atau memperbarui.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.
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"
]
}
}
]
}$refiddari perintah sebelumnya dalam request yang sama.pathPath 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
}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 atasemail,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).Bersarangfields.<key>,stats.<key>, danlists.<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 / detikPuncak 15. Respons yang disajikan dari cache juga dihitung.
15 bersamaanMaksimal 15 request diproses pada saat yang sama.
Gunakan batch, bukan loopSatu request bisa membawa 20 perintah masing-masing 500 kontak: 10.000 kontak per request.
Cache baca: 1,5 dtkPembacaan 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 dtkPenulisan yang sama yang diulang dalam 1,5 detik mengembalikan hasil pertama tanpa menulis lagi, jadi klik ganda tidak mengimpor dua kali.
Invalidasi cacheSetiap penulisan langsung membersihkan cache baca Anda, jadi pembacaan berikutnya melihat kondisi terbaru.
Batas
Tag50 per kontak.
List75 per kontak.
Custom field100 per akun.
Data custom list50 key per list.
TeksField
textmenampung hingga 2.000 karakter. Field profil (first_name…) menampung hingga 256.
Konvensi
Aturan ini berlaku untuk semua perintah.
Satu kontak per emailKontak adalah milik akun Anda, bukan milik list. List, tag, field, dan status adalah atribut kontak.
EmailDisimpan dalam huruf kecil tanpa spasi.
Ana@Acme.comdanana@acme.comadalah kontak yang sama.Huruf besar/kecil dan aksenTag, opsi enum, dan pencocokan teks mengabaikan huruf besar/kecil dan aksen:
"são paulo"cocok dengan"Sao Paulo". Tag disimpan dalam bentuk ternormalisasi.PaginasiDaftar yang bisa bertambah mengembalikan
has_moredannext_cursor. Kirimnext_cursorsebagaicursordi panggilan berikutnya, dengan argumen lain yang sama.PenghapusanMenghapus 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.
- 400
INVALID_JSONBody bukan {"commands":[...]} atau lebih besar dari 1 MB.
- 400
INVALID_ARGSRequest tidak memiliki perintah atau lebih dari 20.
- 401
MISSING_AUTH_HEADERTidak ada header Authorization yang dikirim.
- 401
INVALID_API_KEYAPI key tidak ada, sudah dicabut, atau dinonaktifkan di dashboard.
- 401
API_KEY_EXPIREDAPI key telah melewati tanggal kedaluwarsa yang diatur di dashboard.
- 401
WRONG_CREDENTIAL_TYPEToken mailbox (S.C.G.…) yang dikirim. Kontak membutuhkan API key dari dashboard.
- 403
IP_NOT_ALLOWEDRequest berasal dari IP yang tidak ada dalam daftar IP yang diizinkan untuk key ini.
- 403
ACCOUNT_BLOCKEDAkun diblokir.
- 403
MISSING_SCOPEKey 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.
- 429
RATE_LIMITEDLebih dari 15 request/detik atau 15 bersamaan untuk IP + API key yang sama. Tunggu sesuai jumlah detik di Retry-After.
- 503
AUTH_UNAVAILABLEAutentikasi sementara tidak tersedia. Coba lagi.
- CMD
UNKNOWN_COMMANDNama perintah tidak ada.
- CMD
INTERNALError server. Detailnya hanya ditulis ke log server.