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.

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

Mesmo envelope de Logs, Contacts e Bounces & Complaints. As páginas abaixo desta documentam cada comando.

i

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ório

    1 a 20 comandos, executados em ordem. O corpo inteiro pode ter até 1 MB.

  • commands[].commandstringobrigatório

    get_preferences, get_many, get_history, list_changes ou set_preferences.

  • commands[].argsobjectopcional

    Os argumentos do comando.

  • commands[].idstringopcional

    Seu 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

  • type

    Sempre SUCCESS quando a requisição em si foi aceita.

  • results[].command

    O comando que gerou este resultado.

  • results[].id

    O id que você enviou, ou o índice do comando.

  • results[].type

    SUCCESS ou ERROR.

  • results[].took_ms

    Tempo que o comando levou dentro do servidor.

  • results[].data

    A saída do comando. Só aparece quando type é SUCCESS.

  • results[].code / message

    O erro. Só aparece quando type é ERROR.

Autenticação

Use a API key que você cria no dashboard, em Developers → API Keys.

  • Authorization

    Envie Authorization: <api key> ou Authorization: Bearer <api key>.

  • privacy:read

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

  • privacy:write

    Set Preferences.

  • Tokens de mailbox

    O token do webmail não funciona aqui. Ele é rejeitado com WRONG_CREDENTIAL_TYPE.

  • IPs permitidos

    Se 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 / segundo

    Pico de 15. Respostas servidas pelo cache também contam.

  • 15 simultâneas

    No máximo 15 requisições sendo processadas ao mesmo tempo.

  • Cache de leitura: 1,5 s

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

  • 400INVALID_JSON

    O corpo não é {"commands":[...]} ou tem mais de 1 MB.

  • 400INVALID_ARGS

    A requisição não tem comandos ou tem mais de 20.

  • 401MISSING_AUTH_HEADER

    Nenhum header Authorization foi enviado.

  • 401INVALID_API_KEY

    A API key não existe, foi revogada ou foi desativada no dashboard.

  • 401API_KEY_EXPIRED

    A API key passou da data de expiração definida no dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Foi enviado um token de mailbox. Esta API precisa de uma API key do dashboard.

  • 403IP_NOT_ALLOWED

    A requisição veio de um IP que não está nos IPs permitidos da key.

  • 403ACCOUNT_BLOCKED

    A conta está bloqueada.

  • 403MISSING_SCOPE

    A key não tem `privacy:read` nem `privacy:write`, então nenhum comando pode rodar.

  • 429RATE_LIMITED

    Mais de 15 requisições/s ou 15 simultâneas para o mesmo IP + API key. Aguarde o número de segundos em Retry-After.

  • 503AUTH_UNAVAILABLE

    A autenticação está temporariamente indisponível. Tente de novo.

  • CMDUNKNOWN_COMMAND

    O nome do comando não existe.

  • CMDINTERNAL

    Erro no servidor. O detalhe só é gravado no log do servidor.