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.

POSThttps://g.sendcorex.com/v1/feedbackcommand: list_feedback
i

Requer o escopo feedback:read na sua API key.

i

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.

i

Os eventos aparecem cerca de 10 segundos depois de acontecerem. Esse pequeno atraso é o que garante que nada seja pulado entre duas consultas.

Argumentos

  • cursorstringopcional

    O next_cursor da chamada anterior. Na primeira vez, comece sem ele (ou com since).

    ex.: "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE"

  • sincestringopcional

    RFC 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[]opcional

    Só 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"]

  • limitnumberopcional

    Eventos 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

  • events

    Os eventos desta chamada, do mais antigo para o mais novo. Cada um tem os campos abaixo.

  • next_cursor

    Envie-o como cursor na próxima chamada. Quando nada novo chegou, é o mesmo cursor que você enviou.

  • has_more

    true quando já há mais eventos esperando: chame de novo na hora em vez de esperar a próxima consulta.

  • events[].email_id

    O ID do email (um UUID): o id que você recebeu ao enviar, e o mesmo id dos Logs e dos webhooks.

  • events[].kind

    O que aconteceu: bounce_hard, bounce_soft, blocked, complaint ou dropped. Veja Tipos abaixo.

  • events[].source

    De onde ficamos sabendo: a resposta SMTP, uma mensagem de bounce, um feedback loop, uma denúncia de abuso… Veja Origens abaixo.

  • events[].recipient

    O endereço para o qual o email foi enviado.

  • events[].from

    O endereço do remetente.

  • events[].campaign_id

    A campanha, quando o email pertence a uma.

  • events[].smtp_code / events[].enhanced_code

    O código que o servidor de destino respondeu, por exemplo 550 e 5.1.1. Só em bounces e bloqueios.

  • events[].diagnostic

    A resposta completa do servidor de destino, ou o motivo informado em uma denúncia de abuso.

  • events[].reporting_mta

    Quem reportou: o servidor que enviou a mensagem de bounce, o endereço do feedback loop, ou web para a página de denúncia.

  • events[].at

    Quando aconteceu. ISO 8601, UTC.

Tipos

  • bounce_hard

    O 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_soft

    Um 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.

  • blocked

    O 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.

  • complaint

    O destinatário marcou o email como spam (feedback loop) ou o denunciou como abuso. Pare de enviar para este endereço.

  • dropped

    A Sendcorex nunca o enviou: conta bloqueada, sem créditos ou endereço inválido.

Origens

  • smtp

    A resposta do servidor de destino enquanto fazíamos a entrega.

  • dsn

    Uma mensagem de bounce que chegou depois no Return-Path, após o servidor ter aceitado o email inicialmente.

  • expired

    O email ainda estava na fila depois de 5 dias e foi abandonado.

  • retries_exhausted

    O servidor de destino continuou adiando e todas as tentativas foram usadas.

  • outgoing

    Parado antes do envio (é o que os eventos dropped trazem).

  • fbl_microsoft / fbl_yahoo / fbl_other

    Uma denúncia de spam do feedback loop do provedor (Outlook/Hotmail, Yahoo/AOL, outros).

  • abuse_mailbox

    Alguém escreveu para o endereço de abuso no header X-Report-Abuse do email.

  • abuse_web

    Algué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);
i

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.

i

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.

  • 401INVALID_API_KEY

    A API key não existe, foi revogada ou foi desativada no dashboard.

  • 429RATE_LIMITED

    Mais de 15 requisições/s ou 15 simultâneas para o mesmo IP + API key. Aguarde o número de segundos em Retry-After.

  • CMDMISSING_SCOPE

    A API key não tem `feedback:read`.

  • CMDINVALID_ARGS

    Um argumento é inválido: tipo desconhecido, `since` que não é RFC 3339, limit fora do intervalo, `email_id` ausente…

  • CMDINVALID_CURSOR

    O cursor está malformado ou veio de outra conta. Comece de novo sem cursor (ou com `since`).

  • CMDINTERNAL

    Erro no servidor. O detalhe só é gravado no log do servidor.