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.

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

Membutuhkan scope feedback:read pada API key Anda.

i

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.

i

Event muncul sekitar 10 detik setelah terjadi. Jeda kecil inilah yang menjamin tidak ada yang terlewat di antara dua polling.

Argumen

  • cursorstringopsional

    next_cursor dari panggilan sebelumnya. Pertama kali, mulai tanpanya (atau dengan since).

    mis. "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE"

  • sincestringopsional

    RFC 3339. Titik awal saat Anda belum punya cursor. Diabaikan jika cursor dikirim. Tanpa keduanya, Anda mulai dari awal rentang 90 hari.

    mis. "2026-10-01T00:00:00Z"

  • kindsstring[]opsional

    Hanya jenis ini: bounce_hard, bounce_soft, blocked, complaint, dropped. String yang dipisahkan koma juga bisa. Tanpa ini Anda mendapatkan semuanya.

    mis. ["bounce_hard", "complaint"]

  • limitnumberopsional

    Event 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

  • events

    Event dari panggilan ini, terlama lebih dulu. Masing-masing memiliki field di bawah.

  • next_cursor

    Kirim sebagai cursor di panggilan berikutnya. Jika tidak ada yang baru, nilainya sama dengan cursor yang Anda kirim.

  • has_more

    true jika masih ada event yang menunggu: panggil lagi segera, jangan menunggu polling berikutnya.

  • events[].email_id

    ID email (sebuah UUID): id yang Anda terima saat mengirim, dan id yang sama dengan di Logs dan webhook.

  • events[].kind

    Apa yang terjadi: bounce_hard, bounce_soft, blocked, complaint, atau dropped. Lihat Jenis di bawah.

  • events[].source

    Dari mana kami mengetahuinya: jawaban SMTP, pesan bounce, feedback loop, laporan penyalahgunaan… Lihat Sumber di bawah.

  • events[].recipient

    Alamat tujuan email.

  • events[].from

    Alamat pengirim.

  • events[].campaign_id

    Kampanyenya, jika email termasuk dalam sebuah kampanye.

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

    Kode yang dijawab server penerima, misalnya 550 dan 5.1.1. Hanya pada bounce dan pemblokiran.

  • events[].diagnostic

    Jawaban lengkap server penerima, atau alasan yang diberikan dalam laporan penyalahgunaan.

  • events[].reporting_mta

    Siapa yang melaporkan: server yang mengirim pesan bounce, alamat feedback loop, atau web untuk halaman laporan.

  • events[].at

    Kapan terjadinya. ISO 8601, UTC.

Jenis

  • bounce_hard

    Alamat tidak ada atau tidak lagi menerima email (5.1.x, sebagian besar 5xx). Hapus dari daftar Anda: mengirim lagi merusak reputasi Anda.

  • bounce_soft

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

  • blocked

    Server penerima menolak pesannya sendiri: filter spam, kebijakan, blocklist, atau autentikasi (5.7.x). Alamatnya baik-baik saja, jadi jangan dihapus: perbaiki apa yang dikirim.

  • complaint

    Penerima menandai email sebagai spam (feedback loop) atau melaporkannya sebagai penyalahgunaan. Berhenti mengirim ke alamat ini.

  • dropped

    Sendcorex tidak pernah mengirimnya: akun diblokir, tidak ada kredit, atau alamat tidak valid.

Sumber

  • smtp

    Jawaban server penerima saat kami melakukan pengiriman.

  • dsn

    Pesan bounce yang datang belakangan ke Return-Path, setelah server awalnya menerima email.

  • expired

    Email masih ada di antrean setelah 5 hari dan dihentikan.

  • retries_exhausted

    Server penerima terus menundanya dan semua percobaan ulang sudah dipakai.

  • outgoing

    Dihentikan sebelum dikirim (inilah yang dibawa event dropped).

  • fbl_microsoft / fbl_yahoo / fbl_other

    Laporan spam dari feedback loop penyedia (Outlook/Hotmail, Yahoo/AOL, lainnya).

  • abuse_mailbox

    Seseorang menulis ke alamat abuse di header X-Report-Abuse email.

  • abuse_web

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

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.

i

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.

  • 401INVALID_API_KEY

    API key tidak ada, telah dicabut, atau dinonaktifkan di dashboard.

  • 429RATE_LIMITED

    Lebih dari 15 request/dtk atau 15 bersamaan untuk IP + API key yang sama. Tunggu sejumlah detik yang ada di Retry-After.

  • CMDMISSING_SCOPE

    API key tidak memiliki `feedback:read`.

  • CMDINVALID_ARGS

    Ada argumen yang tidak valid: jenis tidak dikenal, `since` bukan RFC 3339, limit di luar rentang, `email_id` tidak ada…

  • CMDINVALID_CURSOR

    Cursor tidak valid atau berasal dari akun lain. Mulai lagi tanpa cursor (atau dengan `since`).

  • CMDINTERNAL

    Error server. Detailnya hanya ditulis ke log server.