Contatos: rotas

Run Commands

O ponto de entrada único para contatos, listas, campos personalizados e segmentos. Envie de 1 a 20 comandos em um request e receba um resultado por comando.

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

Toda ação (importar, marcar com tag, consultar, descadastrar, criar uma lista…) é um comando enviado para esta rota. As páginas abaixo desta documentam cada comando e seus argumentos.

i

Os erros são informados por comando, e as ações em lote informam por email. 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

    O nome do comando, por exemplo upsert_contacts.

  • commands[].argsobjectopcional

    Os argumentos do comando. Qualquer valor pode ser um $ref para o resultado de um comando anterior.

  • commands[].idstringopcional

    Seu próprio identificador para o resultado. Padrão: o índice ("0", "1"…). Obrigatório se você quiser usar $ref.

Início rápido

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);
}

Resposta

{
  "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
        }
      }
    }
  ]
}

Campos da resposta

  • type

    Sempre SUCCESS quando o request em si foi aceito.

  • 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. O resto do tempo do request é rede.

  • results[].data

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

  • results[].code / message

    O erro. Só presente quando type é ERROR.

Autenticação

Contatos usam a API key que você cria no dashboard, em Developers → API Keys. É o mesmo tipo de chave usado para enviar emails, e ela não expira a menos que você defina uma data de expiração.

  • Authorization

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

  • Tokens de mailbox

    O token do webmail (S.C.G.…) não funciona aqui. Ele é rejeitado com WRONG_CREDENTIAL_TYPE.

  • IPs permitidos

    Se a chave tiver uma lista de IPs permitidos, requests de outros IPs recebem 403 IP_NOT_ALLOWED.

  • Revogação

    As chaves ficam em cache por 60 segundos, então uma chave revogada para de funcionar em até um minuto. A data de expiração é verificada em todo request.

!

Mantenha a chave no seu servidor. Qualquer pessoa com ela pode ler e alterar seus contatos.

Scopes

Cada comando precisa de um scope na chave. Quando falta um scope, só aquele comando falha com MISSING_SCOPE; o resto do request roda normalmente. Uma chave sem nenhum scope contact:* recebe 403 MISSING_SCOPE antes de qualquer comando rodar.

  • 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, porque cria ou atualiza.

  • 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 um resultado anterior com $ref

Qualquer valor dentro de args pode ser {"$ref": "<id>", "path": "<path>"}. Ele é substituído pelo valor encontrado em path no resultado do comando com aquele id. Em path, * percorre uma lista e achata o resultado. Este request encontra todos os contatos do plano pro ou business e adiciona uma tag a eles, em uma única ida e volta.

Corpo do request

{
  "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

    O id de um comando anterior no mesmo request.

  • path

    Caminho separado por barras dentro daquele resultado. * passa por todos os itens de uma lista.

Ações em lote

As ações recebem emails (até 500) ou email (só um) e respondem email a email. Um email inválido falha sozinho, sem parar os outros.

data de uma ação em lote

{
  "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 significa que o contato já estava assim, então nada foi gravado. Envie return_contacts: true para receber o contato inteiro em cada item.

Peça só o que você precisa

Sem select, todo contato volta inteiro. Com ele, só voltam as partes que você nomear, e email sempre volta. Funciona em get_contacts, query_contacts, run_segment e list_members com hydrate. Uma consulta só de email é respondida pelo índice e é a leitura mais rápida que existe.

Corpo do request

{
  "commands": [
    {
      "command": "query_contacts",
      "args": {
        "where": {
          "list": "customers",
          "sendable": true
        },
        "select": [
          "first_name",
          "status",
          "fields.plan",
          "stats.open_count"
        ]
      }
    }
  ]
}
  • Nível superior

    email, domain, status, status_reason, status_at, created_at, updated_at, tags, lists, fields, stats e os campos de perfil (first_name, last_name, phone, company, locale, timezone, source).

  • Aninhados

    fields.<key>, stats.<key> e lists.<list_id> retornam só aquela parte. Pedir o nível superior inteiro (fields) prevalece sobre suas subchaves.

Rate limits e cache

Os limites valem por IP + API key. Não há fila: quando você passa do limite, o request é rejeitado com HTTP 429 e um header Retry-After.

  • 15 requests / segundo

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

  • 15 simultâneos

    No máximo 15 requests sendo processados ao mesmo tempo.

  • Use lotes em vez de loops

    Um request pode levar 20 comandos de 500 contatos cada: 10.000 contatos por request.

  • Cache de leitura: 1,5 s

    A mesma leitura (mesmo comando e args) em até 1,5 segundo retorna o mesmo resultado, e leituras idênticas simultâneas compartilham uma única consulta.

  • Deduplicação de escrita: 1,5 s

    A mesma escrita repetida em até 1,5 segundo retorna o primeiro resultado sem gravar de novo, então um clique duplo não importa duas vezes.

  • Invalidação do cache

    Qualquer escrita limpa seu cache de leitura na hora, então a próxima leitura vê o estado novo.

Limites

  • Tags

    50 por contato.

  • Listas

    75 por contato.

  • Campos personalizados

    100 por conta.

  • Dados personalizados da lista

    50 chaves por lista.

  • Texto

    Um campo text guarda até 2.000 caracteres. Campos de perfil (first_name…) guardam até 256.

Convenções

Estas regras valem para todos os comandos.

  • Um contato por email

    Um contato pertence à sua conta, não a uma lista. Listas, tags, campos e status são atributos do contato.

  • Emails

    Salvos em minúsculas e sem espaços. Ana@Acme.com e ana@acme.com são o mesmo contato.

  • Maiúsculas e acentos

    Tags, opções de enum e comparação de texto ignoram maiúsculas e acentos: "são paulo" corresponde a "Sao Paulo". As tags são salvas normalizadas.

  • Paginação

    Listagens que podem crescer retornam has_more e next_cursor. Envie next_cursor como cursor na próxima chamada, com os mesmos outros argumentos.

  • Exclusões

    Excluir uma lista ou um campo vale na hora; os valores são removidos dos contatos em segundo plano (purging: true).

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

    O request 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 (S.C.G.…). Contatos precisam de uma API key do dashboard.

  • 403IP_NOT_ALLOWED

    O request veio de um IP que não está nos IPs permitidos da chave.

  • 403ACCOUNT_BLOCKED

    A conta está bloqueada.

  • 403MISSING_SCOPE

    A chave não tem nenhum scope contact:*, então nenhum comando pode rodar. Quando falta só um scope, só aquele comando falha, com HTTP 200.

  • 429RATE_LIMITED

    Mais de 15 requests/s ou 15 simultâneos para o mesmo IP + API key. Espere 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.