Bounces & Complaints: Rute

Run Commands

Satu-satunya titik masuk untuk bounce dan keluhan. Kirim 1 hingga 20 perintah dalam satu request dan dapatkan satu hasil per perintah.

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

Envelope-nya sama dengan Logs dan Contacts: setiap pembacaan adalah perintah yang dikirim ke rute ini. Halaman-halaman di bawah ini mendokumentasikan setiap perintah.

i

Error dilaporkan per perintah. Perintah yang gagal tidak menghentikan perintah lain, dan status HTTP tetap 200.

Parameter body

  • commandsobject[]wajib

    1 hingga 20 perintah, dijalankan berurutan. Seluruh body bisa berukuran hingga 1 MB.

  • commands[].commandstringwajib

    list_feedback atau get_email.

  • commands[].argsobjectopsional

    Argumen perintah. Nilai apa pun bisa berupa $ref ke hasil perintah sebelumnya.

  • commands[].idstringopsional

    Pengenal Anda sendiri untuk hasilnya. Default-nya indeks ("0", "1"…). Wajib jika Anda ingin memakai $ref.

Mulai cepat

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

Respons

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

Field respons

  • type

    Selalu SUCCESS jika request itu sendiri diterima.

  • results[].command

    Perintah yang menghasilkan hasil ini.

  • results[].id

    id yang Anda kirim, atau indeks perintah.

  • results[].type

    SUCCESS atau ERROR.

  • results[].took_ms

    Waktu yang dibutuhkan perintah di dalam server.

  • results[].data

    Output perintah. Hanya ada jika type bernilai SUCCESS.

  • results[].code / message

    Error-nya. Hanya ada jika type bernilai ERROR.

Autentikasi

Gunakan API key yang Anda buat di dashboard, di Developers → API Keys, dengan scope feedback:read.

  • Authorization

    Kirim Authorization: <api key> atau Authorization: Bearer <api key>.

  • feedback:read

    Satu-satunya scope yang dibutuhkan rute ini. Hanya baca.

  • Token mailbox

    Token webmail tidak berfungsi di sini. Token itu ditolak dengan WRONG_CREDENTIAL_TYPE.

  • IP yang diizinkan

    Jika key memiliki allowlist IP, request dari IP lain mendapat 403 IP_NOT_ALLOWED.

Isi feed

  • Hanya yang tidak sampai

    Hard dan soft bounce, pemblokiran, keluhan spam, dan email yang tidak pernah kami kirim. Email yang terkirim tidak ada di sini: email itu ada di Logs.

  • Satu event per email dan jenis

    Jika server menolak email dan pesan bounce untuknya datang belakangan, Anda mendapat satu event, bukan dua. Begitu juga untuk laporan feedback loop ditambah laporan penyalahgunaan.

  • Hanya hasil akhir

    Penundaan sementara dan percobaan ulang tidak pernah muncul. Soft bounce baru dicatat saat kami menyerah.

  • 90 hari

    Event disimpan selama 90 hari.

  • Tanpa warm-up

    Email yang dikirim oleh warm-up inbox tidak pernah muncul.

Rate limit dan cache

Batas berlaku per IP + API key. Jika Anda melewatinya, request ditolak dengan HTTP 429 dan header Retry-After.

  • 15 request / detik

    Puncak 15. Respons yang disajikan dari cache juga dihitung.

  • 15 bersamaan

    Paling banyak 15 request diproses pada saat yang sama.

  • Cache baca: 1,5 dtk

    Pembacaan yang sama dalam 1,5 detik mengembalikan hasil yang sama. Polling setiap beberapa detik tidak masalah.

Error

Error di level HTTP mengembalikan type, code, dan message. Error yang ditandai CMD dikembalikan di dalam hasil perintah, dengan HTTP 200.

  • 400INVALID_JSON

    Body bukan {"commands":[...]} atau lebih besar dari 1 MB.

  • 400INVALID_ARGS

    Request tidak memiliki perintah atau lebih dari 20.

  • 401MISSING_AUTH_HEADER

    Tidak ada header Authorization yang dikirim.

  • 401INVALID_API_KEY

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

  • 401API_KEY_EXPIRED

    API key telah melewati tanggal kedaluwarsa yang diatur di dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Yang dikirim adalah token mailbox. Feedback API membutuhkan API key dari dashboard.

  • 403IP_NOT_ALLOWED

    Request berasal dari IP yang tidak termasuk IP yang diizinkan untuk key ini.

  • 403ACCOUNT_BLOCKED

    Akun diblokir.

  • 403MISSING_SCOPE

    Key tidak memiliki `feedback:read`, jadi tidak ada perintah yang bisa dijalankan.

  • 429RATE_LIMITED

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

  • 503AUTH_UNAVAILABLE

    Autentikasi sementara tidak tersedia. Coba lagi.

  • CMDUNKNOWN_COMMAND

    Nama perintah tidak ada.

  • CMDINTERNAL

    Error server. Detailnya hanya ditulis ke log server.