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.
https://g.sendcorex.com/v1/privacySame envelope as Logs, Contacts and Bounces & Complaints. The pages below this one document each command.
Errors are reported per command. 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[].commandstringrequiredget_preferences,get_many,get_history,list_changesorset_preferences.commands[].argsobjectoptionalThe command arguments.
commands[].idstringoptionalYour 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
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.
results[].dataThe command output. Only present when
typeisSUCCESS.results[].code / messageThe error. Only present when
typeisERROR.
Authentication
Use the API key you create in the dashboard, under Developers → API Keys.
AuthorizationSend
Authorization: <api key>orAuthorization: Bearer <api key>.privacy:readGet Preferences, Get Many, Get History and List Changes.
privacy:writeSet Preferences.
Mailbox tokensThe webmail token does not work here. It is rejected with
WRONG_CREDENTIAL_TYPE.Allowed IPsIf 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 / secondPeak of 15. Responses served from the cache count too.
15 in flightAt most 15 requests being processed at the same time.
Read cache: 1.5 sThe 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.
- 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 was sent. This API needs 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 neither `privacy:read` nor `privacy:write`, so no command can run.
- 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.