Bounces & Complaints: Rotas
Run Commands
O ponto de entrada único para bounces e reclamações. Envie de 1 a 20 comandos em uma requisição e receba um resultado por comando.
https://g.sendcorex.com/v1/feedbackMesmo envelope de Logs e Contacts: toda leitura é um comando enviado para esta rota. 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óriolist_feedbackouget_email.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/feedback',
{
commands: [
{
command: "list_feedback",
id: "new",
args: {
cursor: "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE",
limit: 100
}
},
{
command: "get_email",
id: "one",
args: {
email_id: "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30"
}
}
]
},
{ 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_feedback",
"id": "new",
"type": "SUCCESS",
"took_ms": 12,
"data": {
"events": [
{
"email_id": "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30",
"kind": "bounce_hard",
"source": "smtp",
"recipient": "old.address@gmail.com",
"from": "noreply@yourdomain.com",
"smtp_code": 550,
"enhanced_code": "5.1.1",
"diagnostic": "550-5.1.1 The email account that you tried to reach does not exist.",
"at": "2026-10-17T05:58:44.031Z"
},
{
"email_id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
"kind": "complaint",
"source": "fbl_microsoft",
"recipient": "ana@outlook.com",
"from": "news@yourdomain.com",
"campaign_id": "c1d2e3f4-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
"reporting_mta": "staff@hotmail.com",
"at": "2026-10-17T09:12:03.500Z"
}
],
"next_cursor": "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE",
"has_more": false
}
},
{
"command": "get_email",
"id": "one",
"type": "SUCCESS",
"took_ms": 4,
"data": {
"events": [
{
"email_id": "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30",
"kind": "bounce_hard",
"source": "smtp",
"recipient": "old.address@gmail.com",
"from": "noreply@yourdomain.com",
"smtp_code": 550,
"enhanced_code": "5.1.1",
"diagnostic": "550-5.1.1 The email account that you tried to reach does not exist.",
"at": "2026-10-17T05:58:44.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, com o escopo feedback:read.
AuthorizationEnvie
Authorization: <api key>ouAuthorization: Bearer <api key>.feedback:readO único escopo de que esta rota precisa. É somente leitura.
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.
O que há no feed
Só o que não chegouHard e soft bounces, bloqueios, reclamações de spam e emails que nunca enviamos. Emails entregues não estão aqui: eles estão nos Logs.
Um evento por email e tipoSe o servidor rejeita um email e depois chega uma mensagem de bounce para ele, você recebe um evento, não dois. O mesmo vale para um relatório de feedback loop mais uma denúncia de abuso.
Só resultados finaisAdiamentos temporários e novas tentativas nunca aparecem. Um soft bounce só é gravado quando desistimos.
90 diasOs eventos ficam guardados por 90 dias.
Sem warm-upEmails enviados pelo warm-up de inbox nunca aparecem.
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. Fazer polling a cada poucos segundos não tem problema.
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. A Feedback 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 `feedback: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.