Logs: Rotas
Run Commands
O ponto de entrada único para os logs de entrega. Envie de 1 a 20 comandos em uma requisição e receba um resultado por comando.
https://g.sendcorex.com/v1/logsÉ o mesmo envelope de Contacts: toda leitura é um comando enviado para esta rota. As páginas abaixo desta documentam cada comando e seus argumentos.
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óriolist_logsouget_logs.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/logs',
{
commands: [
{
command: "list_logs",
id: "bounces",
args: {
status: "bounced",
limit: 20
}
},
{
command: "get_logs",
id: "one",
args: {
id: "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f"
}
}
]
},
{ 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_logs",
"id": "bounces",
"type": "SUCCESS",
"took_ms": 21,
"data": {
"logs": [
{
"id": "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30",
"to": "old.address@gmail.com",
"from": "noreply@yourdomain.com",
"domain": "gmail.com",
"from_domain": "yourdomain.com",
"subject": "Your order #1042 has shipped",
"status": "bounced",
"status_code": 6,
"response": "550 5.1.1 The email account that you tried to reach does not exist.",
"message": null,
"blocked": false,
"block_reason": null,
"retries": 0,
"tracking_id": "7CK-JDL-Z2M-20261017",
"sent_at": "2026-10-17T05:58:44.031Z",
"updated_at": "2026-10-17T05:58:45.600Z"
}
],
"count": 1,
"has_more": false,
"next_cursor": null,
"partial": false
}
},
{
"command": "get_logs",
"id": "one",
"type": "SUCCESS",
"took_ms": 9,
"data": {
"logs": [
{
"id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
"to": "ana@acme.com",
"from": "noreply@yourdomain.com",
"domain": "acme.com",
"from_domain": "yourdomain.com",
"subject": "Your order #1042 has shipped",
"status": "delivered",
"status_code": 2,
"response": "250 2.0.0 OK 1760684401 a1si123456",
"message": null,
"blocked": false,
"block_reason": null,
"retries": 0,
"tracking_id": "7CK-JDL-Y1L-20261017",
"sent_at": "2026-10-17T06:00:01.204Z",
"updated_at": "2026-10-17T06:00:02.913Z"
}
],
"not_found": []
}
}
]
}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. O resto do tempo da requisição é rede.
results[].dataA saída do comando. Só aparece quando
typeéSUCCESS.results[].code / messageO erro. Só aparece quando
typeéERROR.
Autenticação
Os logs usam a API key que você cria no dashboard, em Developers → API Keys, com o escopo logs:read. É o mesmo tipo de key usado para enviar email e gerenciar contatos.
AuthorizationEnvie
Authorization: <api key>ouAuthorization: Bearer <api key>.logs:readO único escopo de que os logs precisam. É somente leitura: nada nesta rota altera dados.
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.RevogaçãoAs keys ficam em cache por 60 segundos, então uma key revogada para de funcionar em até um minuto. A data de expiração é verificada em toda requisição.
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 esse id. Em path, * percorre uma lista. Esta requisição lista os bounces mais recentes e lê os corpos deles, em uma única ida e volta.
Corpo da requisição
{
"commands": [
{
"command": "list_logs",
"id": "b",
"args": {
"status": "bounced",
"limit": 10
}
},
{
"command": "get_logs",
"args": {
"ids": {
"$ref": "b",
"path": "logs/*/id"
},
"include_content": true
}
}
]
}O que há nos logs
Todo envioCada email que você envia ganha um log, que é atualizado conforme a entrega tem um resultado.
60 diasOs logs ficam guardados por 60 dias. Os mais antigos somem, e os ids deles voltam em
not_found.Sem warm-upEmails enviados pelo warm-up de inbox nunca aparecem, então o polling só retorna o seu tráfego real.
Sem corpo por padrãoListas nunca trazem o HTML. Get Logs só o retorna com
include_content: true.
Rate limits e cache
Os limites valem por IP + API key. Não há fila: 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. Percorrer muitas páginas em paralelo é o jeito mais comum de atingir esse limite: percorra uma depois da outra.
Cache de leitura: 1,5 sA mesma leitura (mesmo comando e args) dentro de 1,5 segundo retorna o mesmo resultado, e leituras idênticas em andamento compartilham uma consulta. Fazer polling a cada poucos segundos não tem problema.
Cursores
List Logs retorna next_cursor enquanto houver mais. Ele é opaco: devolva-o como veio, com os mesmos filtros.
next_cursor
{
"has_more": true,
"next_cursor": "MDAwMDAwMDA4MzowOjgyMzkzMTU5OTg3OTU6M2YyYTFi",
"partial": false
}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. Os logs precisam 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 `logs:read`, 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.