Contacts: Routes
Run Commands
The single entry point for contacts, lists, custom fields and segments. Send 1 to 20 commands in one request and get one result per command.
https://g.sendcorex.com/v1/contactsEvery action (import, tag, query, unsubscribe, create a list…) is a command sent to this route. The pages below this one document each command and its arguments.
Errors are reported per command, and bulk actions report per email. A command that fails does not stop the others, and the HTTP status stays 200.
Body parameters
commandsobject[]required1 to 20 commands, executed in order. The whole body can have up to 1 MB.
commands[].commandstringrequiredThe command name, for example
upsert_contacts.commands[].argsobjectoptionalThe command arguments. Any value can be a
$refto the result of an earlier command.commands[].idstringoptionalYour own identifier for the result. Defaults to the index (
"0","1"…). Required if you want to use$ref.
Quick start
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);
}Response
{
"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
}
}
}
]
}Response fields
typeAlways
SUCCESSwhen the request itself was accepted.results[].commandThe command that produced this result.
results[].idThe
idyou sent, or the index of the command.results[].typeSUCCESSorERROR.results[].took_msTime the command took inside the server. The rest of the request time is network.
results[].dataThe command output. Only present when
typeisSUCCESS.results[].code / messageThe error. Only present when
typeisERROR.
Authentication
Contacts use the API key you create in the dashboard, under Developers → API Keys. It is the same kind of key used to send email, and it does not expire unless you set an expiration date on it.
AuthorizationSend
Authorization: <api key>orAuthorization: Bearer <api key>.Mailbox tokensThe webmail token (
S.C.G.…) does not work here. It is rejected withWRONG_CREDENTIAL_TYPE.Allowed IPsIf the key has an IP allowlist, requests from other IPs get
403 IP_NOT_ALLOWED.RevokingKeys are cached for 60 seconds, so a revoked key stops working within a minute. The expiration date is checked on every request.
Keep the key on your server. Anyone with it can read and change your contacts.
Scopes
Each command needs one scope on the key. When a scope is missing, only that command fails with MISSING_SCOPE; the rest of the request runs normally. A key with no contact:* scope at all gets 403 MISSING_SCOPE before any command runs.
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, because it creates or updates.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.
Use a previous result with $ref
Any value inside args can be {"$ref": "<id>", "path": "<path>"}. It is replaced by the value found at path in the result of the command with that id. In path, * walks a list and flattens the result. This request finds every contact on the pro or business plan and tags them, in one round trip.
Request body
{
"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"
]
}
}
]
}$refThe
idof an earlier command in the same request.pathSlash-separated path into that result.
*goes through every item of a list.
Bulk actions
Actions take emails (up to 500) or email (just one) and answer email by email. A bad email fails on its own, without stopping the others.
data of a bulk action
{
"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 means the contact was already like that, so nothing was written. Send return_contacts: true to get the whole contact back in each item.
Ask only for what you need
Without select, every contact comes back whole. With it, only the parts you name come back, and email always does. It works on get_contacts, query_contacts, run_segment and list_members with hydrate. An email-only query is answered from the index and is the fastest read there is.
Request body
{
"commands": [
{
"command": "query_contacts",
"args": {
"where": {
"list": "customers",
"sendable": true
},
"select": [
"first_name",
"status",
"fields.plan",
"stats.open_count"
]
}
}
]
}Top levelemail,domain,status,status_reason,status_at,created_at,updated_at,tags,lists,fields,statsand the profile fields (first_name,last_name,phone,company,locale,timezone,source).Nestedfields.<key>,stats.<key>andlists.<list_id>return just that part. Asking for the whole top level (fields) wins over its sub-keys.
Rate limits and cache
Limits apply per IP + API key. There is no queue: when you go over, the request is rejected with HTTP 429 and a Retry-After header.
15 requests / secondPeak of 15. Responses served from the cache count too.
15 in flightAt most 15 requests being processed at the same time.
Batch instead of loopingOne request can carry 20 commands of 500 contacts each: 10,000 contacts per request.
Read cache: 1.5 sThe same read (same command and args) within 1.5 seconds returns the same result, and identical reads in flight share one query.
Write de-duplication: 1.5 sThe same write repeated within 1.5 seconds returns the first result without writing again, so a double click does not import twice.
Cache invalidationAny write clears your read cache right away, so the next read sees the new state.
Limits
Tags50 per contact.
Lists75 per contact.
Custom fields100 per account.
List custom data50 keys per list.
TextA
textfield holds up to 2,000 characters. Profile fields (first_name…) hold up to 256.
Conventions
These rules are shared by all commands.
One contact per emailA contact belongs to your account, not to a list. Lists, tags, fields and status are attributes of the contact.
EmailsStored in lower case without spaces.
Ana@Acme.comandana@acme.comare the same contact.Case and accentsTags, enum options and text matching ignore case and accents:
"são paulo"matches"Sao Paulo". Tags are stored normalized.PaginationLists that can grow return
has_moreandnext_cursor. Sendnext_cursorascursorin the next call, with the same other arguments.DeletesDeleting a list or a field takes effect immediately; the values are removed from the contacts in the background (
purging: true).
Errors
HTTP-level errors return type, code and message. Errors marked CMD come back inside the command result, with HTTP 200.
- 400
INVALID_JSONThe body is not {"commands":[...]} or is larger than 1 MB.
- 400
INVALID_ARGSThe request has no commands or more than 20.
- 401
MISSING_AUTH_HEADERNo Authorization header was sent.
- 401
INVALID_API_KEYThe API key does not exist, was revoked or was disabled in the dashboard.
- 401
API_KEY_EXPIREDThe API key passed the expiration date set in the dashboard.
- 401
WRONG_CREDENTIAL_TYPEA mailbox token (S.C.G.…) was sent. Contacts need a dashboard API key.
- 403
IP_NOT_ALLOWEDThe request came from an IP that is not in the allowed IPs of the key.
- 403
ACCOUNT_BLOCKEDThe account is blocked.
- 403
MISSING_SCOPEThe key has no contact:* scope at all, so no command can run. When only one scope is missing, just that command fails, with HTTP 200.
- 429
RATE_LIMITEDMore than 15 requests/s or 15 in flight for the same IP + API key. Wait the number of seconds in Retry-After.
- 503
AUTH_UNAVAILABLEAuthentication is temporarily unavailable. Try again.
- CMD
UNKNOWN_COMMANDThe command name does not exist.
- CMD
INTERNALServer error. The detail is only written to the server log.