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.
https://g.sendcorex.com/v1/feedbackcommand: list_feedbackNeeds the feedback:read scope on your API key.
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.
Events show up about 10 seconds after they happen. That small delay is what guarantees nothing is skipped between two polls.
Arguments
cursorstringoptionalThe
next_cursorof the previous call. Start without it (or withsince) the first time.e.g.
"ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE"sincestringoptionalRFC 3339. Where to start when you have no cursor yet. Ignored when
cursoris sent. Without both, you start at the beginning of the 90 days.e.g.
"2026-10-01T00:00:00Z"kindsstring[]optionalOnly 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"]limitnumberoptionalEvents 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
eventsThe events of this call, oldest first. Each one has the fields below.
next_cursorSend it as
cursoron the next call. When nothing new arrived it is the same cursor you sent.has_moretruewhen more events are already waiting: call again right away instead of waiting for your next poll.events[].email_idThe email ID (a UUID): the
idyou got back when you sent, and the same id as in Logs and webhooks.events[].kindWhat happened:
bounce_hard,bounce_soft,blocked,complaintordropped. See Kinds below.events[].sourceWhere we learned it from: the SMTP answer, a bounce message, a feedback loop, an abuse report… See Sources below.
events[].recipientThe address the email was sent to.
events[].fromThe sender address.
events[].campaign_idThe campaign, when the email belongs to one.
events[].smtp_code / events[].enhanced_codeThe code the recipient server answered, for example
550and5.1.1. Only on bounces and blocks.events[].diagnosticThe full answer of the recipient server, or the reason given in an abuse report.
events[].reporting_mtaWho reported it: the server that sent the bounce message, the feedback loop address, or
webfor the abuse page.events[].atWhen it happened. ISO 8601, UTC.
Kinds
bounce_hardThe 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_softA 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.
blockedThe 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.
complaintThe recipient marked the email as spam (feedback loop) or reported it as abuse. Stop sending to this address.
droppedSendcorex never sent it: account blocked, no credits, or an invalid address.
Sources
smtpThe answer of the recipient server while we were delivering.
dsnA bounce message that arrived later at the Return-Path, after the server had first accepted the email.
expiredThe email was still in the queue after 5 days and was given up.
retries_exhaustedThe recipient server kept deferring it and every retry was used.
outgoingStopped before sending (this is what
droppedevents carry).fbl_microsoft / fbl_yahoo / fbl_otherA spam report from the provider feedback loop (Outlook/Hotmail, Yahoo/AOL, others).
abuse_mailboxSomeone wrote to the abuse address in the
X-Report-Abuseheader of the email.abuse_webSomeone used the report page linked in the
X-Report-Abuseheader.
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);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.
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.
- 401
INVALID_API_KEYThe API key does not exist, was revoked or was disabled in the dashboard.
- 429
RATE_LIMITEDMore than 15 requests/s or 15 in flight for the same IP + API key. Wait the number of seconds in Retry-After.
- CMD
MISSING_SCOPEThe API key does not have `feedback:read`.
- CMD
INVALID_ARGSAn argument is invalid: unknown kind, `since` that is not RFC 3339, limit out of range, missing `email_id`…
- CMD
INVALID_CURSORThe cursor is malformed or came from a different account. Start again without a cursor (or with `since`).
- CMD
INTERNALServer error. The detail is only written to the server log.