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.

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

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

i

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[]required

    1 to 20 commands, executed in order. The whole body can have up to 1 MB.

  • commands[].commandstringrequired

    The command name, for example upsert_contacts.

  • commands[].argsobjectoptional

    The command arguments. Any value can be a $ref to the result of an earlier command.

  • commands[].idstringoptional

    Your 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

  • type

    Always SUCCESS when the request itself was accepted.

  • results[].command

    The command that produced this result.

  • results[].id

    The id you sent, or the index of the command.

  • results[].type

    SUCCESS or ERROR.

  • results[].took_ms

    Time the command took inside the server. The rest of the request time is network.

  • results[].data

    The command output. Only present when type is SUCCESS.

  • results[].code / message

    The error. Only present when type is ERROR.

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.

  • Authorization

    Send Authorization: <api key> or Authorization: Bearer <api key>.

  • Mailbox tokens

    The webmail token (S.C.G.…) does not work here. It is rejected with WRONG_CREDENTIAL_TYPE.

  • Allowed IPs

    If the key has an IP allowlist, requests from other IPs get 403 IP_NOT_ALLOWED.

  • Revoking

    Keys 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: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, because it creates or updates.

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

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"
        ]
      }
    }
  ]
}
  • $ref

    The id of an earlier command in the same request.

  • path

    Slash-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
}
i

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 level

    email, domain, status, status_reason, status_at, created_at, updated_at, tags, lists, fields, stats and the profile fields (first_name, last_name, phone, company, locale, timezone, source).

  • Nested

    fields.<key>, stats.<key> and lists.<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 / second

    Peak of 15. Responses served from the cache count too.

  • 15 in flight

    At most 15 requests being processed at the same time.

  • Batch instead of looping

    One request can carry 20 commands of 500 contacts each: 10,000 contacts per request.

  • Read cache: 1.5 s

    The 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 s

    The same write repeated within 1.5 seconds returns the first result without writing again, so a double click does not import twice.

  • Cache invalidation

    Any write clears your read cache right away, so the next read sees the new state.

Limits

  • Tags

    50 per contact.

  • Lists

    75 per contact.

  • Custom fields

    100 per account.

  • List custom data

    50 keys per list.

  • Text

    A text field 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 email

    A contact belongs to your account, not to a list. Lists, tags, fields and status are attributes of the contact.

  • Emails

    Stored in lower case without spaces. Ana@Acme.com and ana@acme.com are the same contact.

  • Case and accents

    Tags, enum options and text matching ignore case and accents: "são paulo" matches "Sao Paulo". Tags are stored normalized.

  • Pagination

    Lists that can grow return has_more and next_cursor. Send next_cursor as cursor in the next call, with the same other arguments.

  • Deletes

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

  • 400INVALID_JSON

    The body is not {"commands":[...]} or is larger than 1 MB.

  • 400INVALID_ARGS

    The request has no commands or more than 20.

  • 401MISSING_AUTH_HEADER

    No Authorization header was sent.

  • 401INVALID_API_KEY

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

  • 401API_KEY_EXPIRED

    The API key passed the expiration date set in the dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    A mailbox token (S.C.G.…) was sent. Contacts need a dashboard API key.

  • 403IP_NOT_ALLOWED

    The request came from an IP that is not in the allowed IPs of the key.

  • 403ACCOUNT_BLOCKED

    The account is blocked.

  • 403MISSING_SCOPE

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

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

  • 503AUTH_UNAVAILABLE

    Authentication is temporarily unavailable. Try again.

  • CMDUNKNOWN_COMMAND

    The command name does not exist.

  • CMDINTERNAL

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