Tracking Preferences: Rotas
Run Commands
O ponto de entrada único para as preferências de tracking. Envie de 1 a 20 comandos em uma requisição e receba um resultado por comando.
https://g.sendcorex.com/v1/privacyMesmo envelope de Logs, Contacts e Bounces & Complaints. As páginas abaixo desta documentam cada comando.
Os erros são reportados por comando. Um comando que falha não interrompe os outros, e o status HTTP continua 200.
Parâmetros do corpo
commandsobject[]obrigatório1 a 20 comandos, executados em ordem. O corpo inteiro pode ter até 1 MB.
commands[].commandstringobrigatórioget_preferences,get_many,get_history,list_changesouset_preferences.commands[].argsobjectopcionalOs argumentos do comando.
commands[].idstringopcionalSeu próprio identificador para o resultado. Padrão: o índice (
"0","1"…).
Início rápido
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);
}Resposta
{
"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"
}
}
}
]
}Campos da resposta
typeSempre
SUCCESSquando a requisição em si foi aceita.results[].commandO comando que gerou este resultado.
results[].idO
idque você enviou, ou o índice do comando.results[].typeSUCCESSouERROR.results[].took_msTempo que o comando levou dentro do servidor.
results[].dataA saída do comando. Só aparece quando
typeéSUCCESS.results[].code / messageO erro. Só aparece quando
typeéERROR.
Autenticação
Use a API key que você cria no dashboard, em Developers → API Keys.
AuthorizationEnvie
Authorization: <api key>ouAuthorization: Bearer <api key>.privacy:readGet Preferences, Get Many, Get History e List Changes.
privacy:writeSet Preferences.
Tokens de mailboxO token do webmail não funciona aqui. Ele é rejeitado com
WRONG_CREDENTIAL_TYPE.IPs permitidosSe a key tem uma allowlist de IPs, requisições de outros IPs recebem
403 IP_NOT_ALLOWED.
Rate limits e cache
Os limites valem por IP + API key. Quando você passa do limite, a requisição é rejeitada com HTTP 429 e um header Retry-After.
15 requisições / segundoPico de 15. Respostas servidas pelo cache também contam.
15 simultâneasNo máximo 15 requisições sendo processadas ao mesmo tempo.
Cache de leitura: 1,5 sA mesma leitura dentro de 1,5 segundo retorna o mesmo resultado. Set Preferences nunca entra em cache.
Erros
Erros no nível HTTP retornam type, code e message. Erros marcados com CMD voltam dentro do resultado do comando, com HTTP 200.
- 400
INVALID_JSONO corpo não é {"commands":[...]} ou tem mais de 1 MB.
- 400
INVALID_ARGSA requisição não tem comandos ou tem mais de 20.
- 401
MISSING_AUTH_HEADERNenhum header Authorization foi enviado.
- 401
INVALID_API_KEYA API key não existe, foi revogada ou foi desativada no dashboard.
- 401
API_KEY_EXPIREDA API key passou da data de expiração definida no dashboard.
- 401
WRONG_CREDENTIAL_TYPEFoi enviado um token de mailbox. Esta API precisa de uma API key do dashboard.
- 403
IP_NOT_ALLOWEDA requisição veio de um IP que não está nos IPs permitidos da key.
- 403
ACCOUNT_BLOCKEDA conta está bloqueada.
- 403
MISSING_SCOPEA key não tem `privacy:read` nem `privacy:write`, então nenhum comando pode rodar.
- 429
RATE_LIMITEDMais de 15 requisições/s ou 15 simultâneas para o mesmo IP + API key. Aguarde o número de segundos em Retry-After.
- 503
AUTH_UNAVAILABLEA autenticação está temporariamente indisponível. Tente de novo.
- CMD
UNKNOWN_COMMANDO nome do comando não existe.
- CMD
INTERNALErro no servidor. O detalhe só é gravado no log do servidor.