Bounces & Complaints: Leitura
Listar feedback
Todo bounce, bloqueio e reclamação da sua conta, do mais antigo para o mais novo, para você consultar com um cursor sem nunca perder nenhum.
https://g.sendcorex.com/v1/feedbackcommand: list_feedbackRequer o escopo feedback:read na sua API key.
Guarde o next_cursor e envie-o na próxima chamada. Ele sempre volta, mesmo quando não houve nada novo, então seu loop nunca precisa tratar uma página vazia como caso especial.
Os eventos aparecem cerca de 10 segundos depois de acontecerem. Esse pequeno atraso é o que garante que nada seja pulado entre duas consultas.
Argumentos
cursorstringopcionalO
next_cursorda chamada anterior. Na primeira vez, comece sem ele (ou comsince).ex.:
"ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE"sincestringopcionalRFC 3339. Por onde começar quando você ainda não tem cursor. Ignorado quando
cursoré enviado. Sem os dois, você começa no início dos 90 dias.ex.:
"2026-10-01T00:00:00Z"kindsstring[]opcionalSó estes tipos:
bounce_hard,bounce_soft,blocked,complaint,dropped. Uma string separada por vírgulas também funciona. Sem ele, você recebe todos.ex.:
["bounce_hard", "complaint"]limitnumberopcionalEventos por chamada, de 1 a 1000. Padrão: 100.
ex.:
100
Início rápido
import axios from 'axios';
const response = await axios.post(
'https://g.sendcorex.com/v1/feedback',
{
commands: [
{
command: "list_feedback",
args: {
cursor: "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE",
kinds: [
"bounce_hard",
"complaint"
],
limit: 100
}
}
]
},
{ headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);
const [result] = response.data.results;
if (result.type !== 'SUCCESS') throw new Error(`${result.code}: ${result.message}`);
console.log(result.data);Resposta
{
"type": "SUCCESS",
"results": [
{
"command": "list_feedback",
"id": "0",
"type": "SUCCESS",
"took_ms": 18,
"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"
},
{
"email_id": "5a6b7c8d-1e2f-4a3b-9c4d-5e6f7a8b9c0d",
"kind": "blocked",
"source": "smtp",
"recipient": "paulo@corp-example.com",
"from": "noreply@yourdomain.com",
"smtp_code": 554,
"enhanced_code": "5.7.1",
"diagnostic": "554 5.7.1 Service unavailable; client host blocked using zen.spamhaus.org",
"at": "2026-10-17T10:40:19.002Z"
}
],
"next_cursor": "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE",
"has_more": false
}
}
]
}Campos da resposta
eventsOs eventos desta chamada, do mais antigo para o mais novo. Cada um tem os campos abaixo.
next_cursorEnvie-o como
cursorna próxima chamada. Quando nada novo chegou, é o mesmo cursor que você enviou.has_moretruequando já há mais eventos esperando: chame de novo na hora em vez de esperar a próxima consulta.events[].email_idO ID do email (um UUID): o
idque você recebeu ao enviar, e o mesmo id dos Logs e dos webhooks.events[].kindO que aconteceu:
bounce_hard,bounce_soft,blocked,complaintoudropped. Veja Tipos abaixo.events[].sourceDe onde ficamos sabendo: a resposta SMTP, uma mensagem de bounce, um feedback loop, uma denúncia de abuso… Veja Origens abaixo.
events[].recipientO endereço para o qual o email foi enviado.
events[].fromO endereço do remetente.
events[].campaign_idA campanha, quando o email pertence a uma.
events[].smtp_code / events[].enhanced_codeO código que o servidor de destino respondeu, por exemplo
550e5.1.1. Só em bounces e bloqueios.events[].diagnosticA resposta completa do servidor de destino, ou o motivo informado em uma denúncia de abuso.
events[].reporting_mtaQuem reportou: o servidor que enviou a mensagem de bounce, o endereço do feedback loop, ou
webpara a página de denúncia.events[].atQuando aconteceu. ISO 8601, UTC.
Tipos
bounce_hardO endereço não existe ou não aceita mais emails (5.1.x, a maioria dos 5xx). Remova-o das suas listas: enviar de novo prejudica sua reputação.
bounce_softUm problema temporário que não se resolveu a tempo: caixa cheia (5.2.2), um 4xx que esgotou as tentativas, ou o email expirou na fila. Você pode tentar de novo mais tarde.
blockedO servidor de destino recusou a própria mensagem: filtro de spam, política, blocklist ou autenticação (5.7.x). O endereço está ok, então não o remova: corrija o que foi enviado.
complaintO destinatário marcou o email como spam (feedback loop) ou o denunciou como abuso. Pare de enviar para este endereço.
droppedA Sendcorex nunca o enviou: conta bloqueada, sem créditos ou endereço inválido.
Origens
smtpA resposta do servidor de destino enquanto fazíamos a entrega.
dsnUma mensagem de bounce que chegou depois no Return-Path, após o servidor ter aceitado o email inicialmente.
expiredO email ainda estava na fila depois de 5 dias e foi abandonado.
retries_exhaustedO servidor de destino continuou adiando e todas as tentativas foram usadas.
outgoingParado antes do envio (é o que os eventos
droppedtrazem).fbl_microsoft / fbl_yahoo / fbl_otherUma denúncia de spam do feedback loop do provedor (Outlook/Hotmail, Yahoo/AOL, outros).
abuse_mailboxAlguém escreveu para o endereço de abuso no header
X-Report-Abusedo email.abuse_webAlguém usou a página de denúncia linkada no header
X-Report-Abuse.
Polling
Guarde o cursor em algum lugar que sobreviva a um restart (uma linha no banco, um arquivo). A cada ciclo, leia até has_more ser false, trate cada evento e salve o novo cursor.
Node.js
let cursor = await loadCursor(); // null the first time
async function poll() {
let more = true;
while (more) {
const [result] = await call({
command: 'list_feedback',
args: cursor ? { cursor, limit: 500 } : { since: new Date(Date.now() - 86400_000).toISOString(), limit: 500 },
});
for (const e of result.data.events) {
if (e.kind === 'bounce_hard' || e.kind === 'complaint') await suppress(e.recipient, e.kind); // your code
}
cursor = result.data.next_cursor;
await saveCursor(cursor);
more = result.data.has_more;
}
}
setInterval(poll, 30_000);call é qualquer helper que faz POST de { commands: [...] } para /v1/feedback e retorna results, como em Run Commands.
Só remova endereços em bounce_hard e complaint. Um evento blocked significa que o servidor recusou aquela mensagem, não que o endereço seja ruim.
Prefere push? Os webhooks bounced e fbl_complaint trazem os mesmos eventos no momento em que acontecem. O polling é a rede de segurança para quando seu endpoint estiver fora do ar.
Filtrando por tipo
Com kinds, o cursor continua avançando pelos eventos que você filtrou, então um loop filtrado custa o mesmo que um sem filtro.
Corpo da requisição
{
"commands": [
{
"command": "list_feedback",
"args": {
"since": "2026-10-01T00:00:00Z",
"kinds": [
"complaint"
]
}
}
]
}O evento
Evento
{
"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"
}Erros
Erros no nível HTTP retornam type, code e message. Erros marcados com CMD voltam dentro do resultado do comando, com HTTP 200.
- 401
INVALID_API_KEYA API key não existe, foi revogada ou foi desativada no dashboard.
- 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.
- CMD
MISSING_SCOPEA API key não tem `feedback:read`.
- CMD
INVALID_ARGSUm argumento é inválido: tipo desconhecido, `since` que não é RFC 3339, limit fora do intervalo, `email_id` ausente…
- CMD
INVALID_CURSORO cursor está malformado ou veio de outra conta. Comece de novo sem cursor (ou com `since`).
- CMD
INTERNALErro no servidor. O detalhe só é gravado no log do servidor.