Contacts: Segments
Run Segment
Get the contacts that match a saved segment right now. Same output and pagination as Query Contacts.
https://g.sendcorex.com/v1/contactscommand: run_segmentNeeds the contact:read scope on your API key.
Arguments
segment_idstringrequiredThe segment to run.
e.g.
"engaged-vips"limitnumberoptionalPage size, from 1 to 1000. Defaults to 50.
cursorstringoptionalThe
next_cursorof the previous page.selectstring[]optionalReturn only these parts of each contact, for example
["status", "fields.plan", "stats.open_count"].emailalways comes back. Without it you get the whole contact.
Quick start
import axios from 'axios';
const response = await axios.post(
'https://g.sendcorex.com/v1/contacts',
{
commands: [
{
command: "run_segment",
args: {
segment_id: "engaged-vips",
select: [
"first_name",
"stats.open_rate"
],
limit: 500
}
}
]
},
{ 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);Response
{
"type": "SUCCESS",
"results": [
{
"command": "run_segment",
"id": "0",
"type": "SUCCESS",
"took_ms": 14,
"data": {
"contacts": [
{
"email": "ana@acme.com",
"first_name": "Ana",
"stats": {
"open_rate": 0.58
}
}
],
"has_more": false,
"next_cursor": null,
"plan": {
"driver": "tag:vip",
"examined": 412,
"keys_only": false,
"ms": {
"scan": 4,
"fetch": 9,
"filter": 1,
"total": 14
}
}
}
}
]
}Response fields
contactsThe matching contacts. Whole contacts, or only the parts you asked for with
select.has_more / next_cursorPagination. While
has_moreistrue, sendnext_cursorascursorwith the samewhereandsort.plan.driverThe index the server picked to scan, for example
tag:viporlist:customers.plan.examinedHow many index entries were read to fill this page.
plan.keys_onlytruewhen the page was answered from the index alone, without loading the contacts.plan.msTime spent scanning, fetching, filtering and in total, in milliseconds.
Errors
HTTP-level errors return type, code and message. Errors marked CMD come back inside the command result, with HTTP 200.
- 401
INVALID_API_KEYThe API key does not exist, was revoked or was disabled in the dashboard.
- 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.
- CMD
MISSING_SCOPEThe API key does not have the scope this command needs. The other commands in the request still run.
- CMD
INVALID_ARGSA required argument is missing or invalid: email, field value, enum option, where key, list id…
- CMD
NOT_FOUNDThe contact, list, field or segment does not exist.
- CMD
INVALID_CURSORThe cursor is malformed or belongs to another query or account.
- CMD
INTERNALServer error. The detail is only written to the server log.