Bounces & Complaints: Membaca
Daftar feedback
Setiap bounce, pemblokiran, dan keluhan di akun Anda, terlama lebih dulu, sehingga Anda bisa polling dengan cursor dan tidak pernah melewatkan satu pun.
https://g.sendcorex.com/v1/feedbackcommand: list_feedbackMembutuhkan scope feedback:read pada API key Anda.
Simpan next_cursor dan kirim di panggilan berikutnya. Nilai ini selalu kembali, bahkan saat tidak ada yang baru, jadi loop Anda tidak perlu menangani halaman kosong secara khusus.
Event muncul sekitar 10 detik setelah terjadi. Jeda kecil inilah yang menjamin tidak ada yang terlewat di antara dua polling.
Argumen
cursorstringopsionalnext_cursordari panggilan sebelumnya. Pertama kali, mulai tanpanya (atau dengansince).mis.
"ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE"sincestringopsionalRFC 3339. Titik awal saat Anda belum punya cursor. Diabaikan jika
cursordikirim. Tanpa keduanya, Anda mulai dari awal rentang 90 hari.mis.
"2026-10-01T00:00:00Z"kindsstring[]opsionalHanya jenis ini:
bounce_hard,bounce_soft,blocked,complaint,dropped. String yang dipisahkan koma juga bisa. Tanpa ini Anda mendapatkan semuanya.mis.
["bounce_hard", "complaint"]limitnumberopsionalEvent per panggilan, dari 1 hingga 1000. Default-nya 100.
mis.
100
Mulai cepat
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);Respons
{
"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
}
}
]
}Field respons
eventsEvent dari panggilan ini, terlama lebih dulu. Masing-masing memiliki field di bawah.
next_cursorKirim sebagai
cursordi panggilan berikutnya. Jika tidak ada yang baru, nilainya sama dengan cursor yang Anda kirim.has_moretruejika masih ada event yang menunggu: panggil lagi segera, jangan menunggu polling berikutnya.events[].email_idID email (sebuah UUID):
idyang Anda terima saat mengirim, dan id yang sama dengan di Logs dan webhook.events[].kindApa yang terjadi:
bounce_hard,bounce_soft,blocked,complaint, ataudropped. Lihat Jenis di bawah.events[].sourceDari mana kami mengetahuinya: jawaban SMTP, pesan bounce, feedback loop, laporan penyalahgunaan… Lihat Sumber di bawah.
events[].recipientAlamat tujuan email.
events[].fromAlamat pengirim.
events[].campaign_idKampanyenya, jika email termasuk dalam sebuah kampanye.
events[].smtp_code / events[].enhanced_codeKode yang dijawab server penerima, misalnya
550dan5.1.1. Hanya pada bounce dan pemblokiran.events[].diagnosticJawaban lengkap server penerima, atau alasan yang diberikan dalam laporan penyalahgunaan.
events[].reporting_mtaSiapa yang melaporkan: server yang mengirim pesan bounce, alamat feedback loop, atau
webuntuk halaman laporan.events[].atKapan terjadinya. ISO 8601, UTC.
Jenis
bounce_hardAlamat tidak ada atau tidak lagi menerima email (5.1.x, sebagian besar 5xx). Hapus dari daftar Anda: mengirim lagi merusak reputasi Anda.
bounce_softMasalah sementara yang tidak teratasi tepat waktu: kotak surat penuh (5.2.2), 4xx yang kehabisan percobaan ulang, atau email kedaluwarsa di antrean. Anda bisa mencoba lagi nanti.
blockedServer penerima menolak pesannya sendiri: filter spam, kebijakan, blocklist, atau autentikasi (5.7.x). Alamatnya baik-baik saja, jadi jangan dihapus: perbaiki apa yang dikirim.
complaintPenerima menandai email sebagai spam (feedback loop) atau melaporkannya sebagai penyalahgunaan. Berhenti mengirim ke alamat ini.
droppedSendcorex tidak pernah mengirimnya: akun diblokir, tidak ada kredit, atau alamat tidak valid.
Sumber
smtpJawaban server penerima saat kami melakukan pengiriman.
dsnPesan bounce yang datang belakangan ke Return-Path, setelah server awalnya menerima email.
expiredEmail masih ada di antrean setelah 5 hari dan dihentikan.
retries_exhaustedServer penerima terus menundanya dan semua percobaan ulang sudah dipakai.
outgoingDihentikan sebelum dikirim (inilah yang dibawa event
dropped).fbl_microsoft / fbl_yahoo / fbl_otherLaporan spam dari feedback loop penyedia (Outlook/Hotmail, Yahoo/AOL, lainnya).
abuse_mailboxSeseorang menulis ke alamat abuse di header
X-Report-Abuseemail.abuse_webSeseorang memakai halaman laporan yang ditautkan di header
X-Report-Abuse.
Polling
Simpan cursor di tempat yang bertahan setelah restart (baris database, file). Pada setiap siklus, baca sampai has_more bernilai false, tangani setiap event, dan simpan cursor yang baru.
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 adalah helper apa pun yang mem-POST { commands: [...] } ke /v1/feedback dan mengembalikan results, seperti di Run Commands.
Hapus alamat hanya untuk bounce_hard dan complaint. Event blocked berarti server menolak pesan itu, bukan berarti alamatnya buruk.
Lebih suka push? Webhook bounced dan fbl_complaint membawa event yang sama saat terjadi. Polling adalah jaring pengaman saat endpoint Anda sedang mati.
Filter berdasarkan jenis
Dengan kinds, cursor tetap bergerak melewati event yang Anda saring, jadi loop yang difilter sama murahnya dengan yang tidak difilter.
Body request
{
"commands": [
{
"command": "list_feedback",
"args": {
"since": "2026-10-01T00:00:00Z",
"kinds": [
"complaint"
]
}
}
]
}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"
}Error
Error di level HTTP mengembalikan type, code, dan message. Error yang ditandai CMD dikembalikan di dalam hasil perintah, dengan HTTP 200.
- 401
INVALID_API_KEYAPI key tidak ada, telah dicabut, atau dinonaktifkan di dashboard.
- 429
RATE_LIMITEDLebih dari 15 request/dtk atau 15 bersamaan untuk IP + API key yang sama. Tunggu sejumlah detik yang ada di Retry-After.
- CMD
MISSING_SCOPEAPI key tidak memiliki `feedback:read`.
- CMD
INVALID_ARGSAda argumen yang tidak valid: jenis tidak dikenal, `since` bukan RFC 3339, limit di luar rentang, `email_id` tidak ada…
- CMD
INVALID_CURSORCursor tidak valid atau berasal dari akun lain. Mulai lagi tanpa cursor (atau dengan `since`).
- CMD
INTERNALError server. Detailnya hanya ditulis ke log server.