Contacts: Segments

Run Segment

Get the contacts that match a saved segment right now. Same output and pagination as Query Contacts.

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

Needs the contact:read scope on your API key.

Arguments

  • segment_idstringrequired

    The segment to run.

    e.g. "engaged-vips"

  • limitnumberoptional

    Page size, from 1 to 1000. Defaults to 50.

  • cursorstringoptional

    The next_cursor of the previous page.

  • selectstring[]optional

    Return only these parts of each contact, for example ["status", "fields.plan", "stats.open_count"]. email always 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

  • contacts

    The matching contacts. Whole contacts, or only the parts you asked for with select.

  • has_more / next_cursor

    Pagination. While has_more is true, send next_cursor as cursor with the same where and sort.

  • plan.driver

    The index the server picked to scan, for example tag:vip or list:customers.

  • plan.examined

    How many index entries were read to fill this page.

  • plan.keys_only

    true when the page was answered from the index alone, without loading the contacts.

  • plan.ms

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

  • 401INVALID_API_KEY

    The API key does not exist, was revoked or was disabled in the dashboard.

  • 429RATE_LIMITED

    More than 15 requests/s or 15 in flight for the same IP + API key. Wait the number of seconds in Retry-After.

  • CMDMISSING_SCOPE

    The API key does not have the scope this command needs. The other commands in the request still run.

  • CMDINVALID_ARGS

    A required argument is missing or invalid: email, field value, enum option, where key, list id…

  • CMDNOT_FOUND

    The contact, list, field or segment does not exist.

  • CMDINVALID_CURSOR

    The cursor is malformed or belongs to another query or account.

  • CMDINTERNAL

    Server error. The detail is only written to the server log.