Tracking Preferences: Routes

Run Commands

The single entry point for tracking preferences. Send 1 to 20 commands in one request and get one result per command.

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

Same envelope as Logs, Contacts and Bounces & Complaints. The pages below this one document each command.

i

Errors are reported per command. 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

    get_preferences, get_many, get_history, list_changes or set_preferences.

  • commands[].argsobjectoptional

    The command arguments.

  • commands[].idstringoptional

    Your own identifier for the result. Defaults to the index ("0", "1"…).

Quick start

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/privacy',
  {
    commands: [
      {
        command: "set_preferences",
        id: "set",
        args: {
          email: "jane.doe@example.com",
          track_opens: false
        }
      },
      {
        command: "get_preferences",
        id: "get",
        args: {
          email: "jane.doe@example.com"
        }
      }
    ]
  },
  { 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": "set_preferences",
      "id": "set",
      "type": "SUCCESS",
      "took_ms": 9,
      "data": {
        "changed": true,
        "preference": {
          "email": "jane.doe@example.com",
          "track_opens": false,
          "track_clicks": true,
          "source": "api",
          "updated_at": "2026-10-24T07:20:12.031Z"
        }
      }
    },
    {
      "command": "get_preferences",
      "id": "get",
      "type": "SUCCESS",
      "took_ms": 3,
      "data": {
        "preference": {
          "email": "jane.doe@example.com",
          "track_opens": false,
          "track_clicks": true,
          "source": "api",
          "updated_at": "2026-10-24T07:20:12.031Z"
        }
      }
    }
  ]
}

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.

  • results[].data

    The command output. Only present when type is SUCCESS.

  • results[].code / message

    The error. Only present when type is ERROR.

Authentication

Use the API key you create in the dashboard, under Developers → API Keys.

  • Authorization

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

  • privacy:read

    Get Preferences, Get Many, Get History and List Changes.

  • privacy:write

    Set Preferences.

  • Mailbox tokens

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

Rate limits and cache

Limits apply per IP + API key. 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.

  • Read cache: 1.5 s

    The same read within 1.5 seconds returns the same result. Set Preferences is never cached.

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 was sent. This API needs 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 neither `privacy:read` nor `privacy:write`, so no command can run.

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