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.
https://g.sendcorex.com/v1/contactsToda 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.
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ório1 a 20 comandos, executados em ordem. O corpo inteiro pode ter até 1 MB.
commands[].commandstringobrigatórioO nome do comando, por exemplo
upsert_contacts.commands[].argsobjectopcionalOs argumentos do comando. Qualquer valor pode ser um
$refpara o resultado de um comando anterior.commands[].idstringopcionalSeu 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
typeSempre
SUCCESSquando o request em si foi aceito.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. O resto do tempo do request é rede.
results[].dataA saída do comando. Só presente quando
typeéSUCCESS.results[].code / messageO 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.
AuthorizationEnvie
Authorization: <api key>ouAuthorization: Bearer <api key>.Tokens de mailboxO token do webmail (
S.C.G.…) não funciona aqui. Ele é rejeitado comWRONG_CREDENTIAL_TYPE.IPs permitidosSe a chave tiver uma lista de IPs permitidos, requests de outros IPs recebem
403 IP_NOT_ALLOWED.RevogaçãoAs 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:readget_contacts,query_contacts,count_contacts,list_events,get_stats,list_fields,list_lists,get_list,list_members,list_segments,get_segment,run_segment.contact:createcreate_list,define_field,save_segment.contact:create + updateupsert_contacts, porque cria ou atualiza.contact:updateupdate_contacts,add_tags,remove_tags,add_to_lists,remove_from_lists,set_list_subscription,set_status,set_fields,unset_fields,update_list.contact:deletedelete_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"
]
}
}
]
}$refO
idde um comando anterior no mesmo request.pathCaminho 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
}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 superioremail,domain,status,status_reason,status_at,created_at,updated_at,tags,lists,fields,statse os campos de perfil (first_name,last_name,phone,company,locale,timezone,source).Aninhadosfields.<key>,stats.<key>elists.<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 / segundoPico de 15. Respostas servidas do cache também contam.
15 simultâneosNo máximo 15 requests sendo processados ao mesmo tempo.
Use lotes em vez de loopsUm request pode levar 20 comandos de 500 contatos cada: 10.000 contatos por request.
Cache de leitura: 1,5 sA 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 sA 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 cacheQualquer escrita limpa seu cache de leitura na hora, então a próxima leitura vê o estado novo.
Limites
Tags50 por contato.
Listas75 por contato.
Campos personalizados100 por conta.
Dados personalizados da lista50 chaves por lista.
TextoUm campo
textguarda até 2.000 caracteres. Campos de perfil (first_name…) guardam até 256.
Convenções
Estas regras valem para todos os comandos.
Um contato por emailUm contato pertence à sua conta, não a uma lista. Listas, tags, campos e status são atributos do contato.
EmailsSalvos em minúsculas e sem espaços.
Ana@Acme.comeana@acme.comsão o mesmo contato.Maiúsculas e acentosTags, 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çãoListagens que podem crescer retornam
has_moreenext_cursor. Envienext_cursorcomocursorna próxima chamada, com os mesmos outros argumentos.ExclusõesExcluir 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.
- 400
INVALID_JSONO corpo não é {"commands":[...]} ou tem mais de 1 MB.
- 400
INVALID_ARGSO request 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 (S.C.G.…). Contatos precisam de uma API key do dashboard.
- 403
IP_NOT_ALLOWEDO request veio de um IP que não está nos IPs permitidos da chave.
- 403
ACCOUNT_BLOCKEDA conta está bloqueada.
- 403
MISSING_SCOPEA 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.
- 429
RATE_LIMITEDMais de 15 requests/s ou 15 simultâneos para o mesmo IP + API key. Espere 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.