Bounces & Complaints: Reading

List Feedback

Every bounce, block and complaint of your account, oldest first, so you can poll with a cursor and never miss one.

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

Needs the feedback:read scope on your API key.

i

Keep next_cursor and send it on the next call. It always comes back, even when there was nothing new, so your loop never has to special-case an empty page.

i

Events show up about 10 seconds after they happen. That small delay is what guarantees nothing is skipped between two polls.

Arguments

  • cursorstringoptional

    The next_cursor of the previous call. Start without it (or with since) the first time.

    e.g. "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE"

  • sincestringoptional

    RFC 3339. Where to start when you have no cursor yet. Ignored when cursor is sent. Without both, you start at the beginning of the 90 days.

    e.g. "2026-10-01T00:00:00Z"

  • kindsstring[]optional

    Only these kinds: bounce_hard, bounce_soft, blocked, complaint, dropped. A comma-separated string also works. Without it you get all of them.

    e.g. ["bounce_hard", "complaint"]

  • limitnumberoptional

    Events per call, from 1 to 1000. Defaults to 100.

    e.g. 100

Quick start

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);

Response

{
  "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
      }
    }
  ]
}

Response fields

  • events

    The events of this call, oldest first. Each one has the fields below.

  • next_cursor

    Send it as cursor on the next call. When nothing new arrived it is the same cursor you sent.

  • has_more

    true when more events are already waiting: call again right away instead of waiting for your next poll.

  • events[].email_id

    The email ID (a UUID): the id you got back when you sent, and the same id as in Logs and webhooks.

  • events[].kind

    What happened: bounce_hard, bounce_soft, blocked, complaint or dropped. See Kinds below.

  • events[].source

    Where we learned it from: the SMTP answer, a bounce message, a feedback loop, an abuse report… See Sources below.

  • events[].recipient

    The address the email was sent to.

  • events[].from

    The sender address.

  • events[].campaign_id

    The campaign, when the email belongs to one.

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

    The code the recipient server answered, for example 550 and 5.1.1. Only on bounces and blocks.

  • events[].diagnostic

    The full answer of the recipient server, or the reason given in an abuse report.

  • events[].reporting_mta

    Who reported it: the server that sent the bounce message, the feedback loop address, or web for the abuse page.

  • events[].at

    When it happened. ISO 8601, UTC.

Kinds

  • bounce_hard

    The address does not exist or no longer accepts mail (5.1.x, most 5xx). Remove it from your lists: sending again hurts your reputation.

  • bounce_soft

    A temporary problem that did not clear in time: mailbox full (5.2.2), a 4xx that ran out of retries, or the email expired in the queue. You can try again later.

  • blocked

    The recipient server refused the message itself: spam filter, policy, blocklist or authentication (5.7.x). The address is fine, so do not remove it: fix what was sent.

  • complaint

    The recipient marked the email as spam (feedback loop) or reported it as abuse. Stop sending to this address.

  • dropped

    Sendcorex never sent it: account blocked, no credits, or an invalid address.

Sources

  • smtp

    The answer of the recipient server while we were delivering.

  • dsn

    A bounce message that arrived later at the Return-Path, after the server had first accepted the email.

  • expired

    The email was still in the queue after 5 days and was given up.

  • retries_exhausted

    The recipient server kept deferring it and every retry was used.

  • outgoing

    Stopped before sending (this is what dropped events carry).

  • fbl_microsoft / fbl_yahoo / fbl_other

    A spam report from the provider feedback loop (Outlook/Hotmail, Yahoo/AOL, others).

  • abuse_mailbox

    Someone wrote to the abuse address in the X-Report-Abuse header of the email.

  • abuse_web

    Someone used the report page linked in the X-Report-Abuse header.

Polling

Store the cursor somewhere that survives a restart (a database row, a file). On every tick, read until has_more is false, handle each event and save the new 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 is any helper that posts { commands: [...] } to /v1/feedback and returns results, as in Run Commands.

!

Only remove addresses on bounce_hard and complaint. A blocked event means the server refused that message, not that the address is bad.

i

Prefer push? The bounced and fbl_complaint webhooks carry the same events the moment they happen. Polling is the safety net when your endpoint was down.

Filtering by kind

With kinds, the cursor still moves past the events you filtered out, so a filtered loop is as cheap as an unfiltered one.

Request body

{
  "commands": [
    {
      "command": "list_feedback",
      "args": {
        "since": "2026-10-01T00:00:00Z",
        "kinds": [
          "complaint"
        ]
      }
    }
  ]
}

The event

Event

{
  "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"
}

Errors

HTTP-level errors return type, code and message. Errors marked CMD come back inside the command result, with HTTP 200.

  • 401INVALID_API_KEY

    The API key does not exist, was revoked or was disabled in the dashboard.

  • 429RATE_LIMITED

    More than 15 requests/s or 15 in flight for the same IP + API key. Wait the number of seconds in Retry-After.

  • CMDMISSING_SCOPE

    The API key does not have `feedback:read`.

  • CMDINVALID_ARGS

    An argument is invalid: unknown kind, `since` that is not RFC 3339, limit out of range, missing `email_id`…

  • CMDINVALID_CURSOR

    The cursor is malformed or came from a different account. Start again without a cursor (or with `since`).

  • CMDINTERNAL

    Server error. The detail is only written to the server log.