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.

POSThttps://g.sendcorex.com/v1/feedback
i

Mesmo envelope de Logs e Contacts: toda leitura é um comando enviado para esta rota. As páginas abaixo desta documentam cada comando.

i

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ório

    1 a 20 comandos, executados em ordem. O corpo inteiro pode ter até 1 MB.

  • commands[].commandstringobrigatório

    list_feedback ou get_email.

  • commands[].argsobjectopcional

    Os argumentos do comando. Qualquer valor pode ser um $ref para o resultado de um comando anterior.

  • commands[].idstringopcional

    Seu 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

  • type

    Sempre SUCCESS quando a requisição em si foi aceita.

  • results[].command

    O comando que gerou este resultado.

  • results[].id

    O id que você enviou, ou o índice do comando.

  • results[].type

    SUCCESS ou ERROR.

  • results[].took_ms

    Tempo que o comando levou dentro do servidor.

  • results[].data

    A saída do comando. Só aparece quando type é SUCCESS.

  • results[].code / message

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

  • Authorization

    Envie Authorization: <api key> ou Authorization: Bearer <api key>.

  • feedback:read

    O único escopo de que esta rota precisa. É somente leitura.

  • Tokens de mailbox

    O token do webmail não funciona aqui. Ele é rejeitado com WRONG_CREDENTIAL_TYPE.

  • IPs permitidos

    Se 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 chegou

    Hard 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 tipo

    Se 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 finais

    Adiamentos temporários e novas tentativas nunca aparecem. Um soft bounce só é gravado quando desistimos.

  • 90 dias

    Os eventos ficam guardados por 90 dias.

  • Sem warm-up

    Emails 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 / segundo

    Pico de 15. Respostas servidas pelo cache também contam.

  • 15 simultâneas

    No máximo 15 requisições sendo processadas ao mesmo tempo.

  • Cache de leitura: 1,5 s

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

  • 400INVALID_JSON

    O corpo não é {"commands":[...]} ou tem mais de 1 MB.

  • 400INVALID_ARGS

    A requisição não tem comandos ou tem mais de 20.

  • 401MISSING_AUTH_HEADER

    Nenhum header Authorization foi enviado.

  • 401INVALID_API_KEY

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

  • 401API_KEY_EXPIRED

    A API key passou da data de expiração definida no dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Foi enviado um token de mailbox. A Feedback API precisa de uma API key do dashboard.

  • 403IP_NOT_ALLOWED

    A requisição veio de um IP que não está nos IPs permitidos da key.

  • 403ACCOUNT_BLOCKED

    A conta está bloqueada.

  • 403MISSING_SCOPE

    A key não tem `feedback:read`, então nenhum comando pode rodar.

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

  • 503AUTH_UNAVAILABLE

    A autenticação está temporariamente indisponível. Tente de novo.

  • CMDUNKNOWN_COMMAND

    O nome do comando não existe.

  • CMDINTERNAL

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