Bounces & Complaints: Routes

Run Commands

The single entry point for bounces and complaints. Send 1 to 20 commands in one request and get one result per command.

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

Same envelope as Logs and Contacts: every read is a command sent to this route. The pages below this one document each command.

i

Errors are reported per command. A command that fails does not stop the others, and the HTTP status stays 200.

Body parameters

  • commandsobject[]required

    1 to 20 commands, executed in order. The whole body can have up to 1 MB.

  • commands[].commandstringrequired

    list_feedback or get_email.

  • commands[].argsobjectoptional

    The command arguments. Any value can be a $ref to the result of an earlier command.

  • commands[].idstringoptional

    Your own identifier for the result. Defaults to the index ("0", "1"…). Required if you want to use $ref.

Quick start

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

Response

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

Response fields

  • type

    Always SUCCESS when the request itself was accepted.

  • results[].command

    The command that produced this result.

  • results[].id

    The id you sent, or the index of the command.

  • results[].type

    SUCCESS or ERROR.

  • results[].took_ms

    Time the command took inside the server.

  • results[].data

    The command output. Only present when type is SUCCESS.

  • results[].code / message

    The error. Only present when type is ERROR.

Authentication

Use the API key you create in the dashboard, under Developers → API Keys, with the feedback:read scope.

  • Authorization

    Send Authorization: <api key> or Authorization: Bearer <api key>.

  • feedback:read

    The only scope this route needs. It is read-only.

  • Mailbox tokens

    The webmail token does not work here. It is rejected with WRONG_CREDENTIAL_TYPE.

  • Allowed IPs

    If the key has an IP allowlist, requests from other IPs get 403 IP_NOT_ALLOWED.

What is in the feed

  • Only what did not arrive

    Hard and soft bounces, blocks, spam complaints and emails we never sent. Delivered emails are not here: they are in Logs.

  • One event per email and kind

    If the server rejects an email and a bounce message for it arrives later, you get one event, not two. Same for a feedback loop report plus an abuse report.

  • Final results only

    Temporary deferrals and retries never show up. A soft bounce is only written when we give up.

  • 90 days

    Events are kept for 90 days.

  • No warm-up

    Emails sent by inbox warm-up never show up.

Rate limits and cache

Limits apply per IP + API key. When you go over, the request is rejected with HTTP 429 and a Retry-After header.

  • 15 requests / second

    Peak of 15. Responses served from the cache count too.

  • 15 in flight

    At most 15 requests being processed at the same time.

  • Read cache: 1.5 s

    The same read within 1.5 seconds returns the same result. Polling every few seconds is fine.

Errors

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

  • 400INVALID_JSON

    The body is not {"commands":[...]} or is larger than 1 MB.

  • 400INVALID_ARGS

    The request has no commands or more than 20.

  • 401MISSING_AUTH_HEADER

    No Authorization header was sent.

  • 401INVALID_API_KEY

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

  • 401API_KEY_EXPIRED

    The API key passed the expiration date set in the dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    A mailbox token was sent. The Feedback API needs a dashboard API key.

  • 403IP_NOT_ALLOWED

    The request came from an IP that is not in the allowed IPs of the key.

  • 403ACCOUNT_BLOCKED

    The account is blocked.

  • 403MISSING_SCOPE

    The key does not have `feedback:read`, so no command can run.

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

  • 503AUTH_UNAVAILABLE

    Authentication is temporarily unavailable. Try again.

  • CMDUNKNOWN_COMMAND

    The command name does not exist.

  • CMDINTERNAL

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