Bounces & Complaints : Lecture

Lister les retours

Chaque bounce, blocage et plainte de votre compte, du plus ancien au plus récent, pour interroger avec un cursor sans jamais en manquer un.

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

Nécessite le scope feedback:read sur votre API key.

i

Conservez next_cursor et envoyez-le au prochain appel. Il revient toujours, même quand il n'y a rien de nouveau, donc votre boucle n'a jamais à traiter une page vide comme un cas particulier.

i

Les événements apparaissent environ 10 secondes après s'être produits. Ce petit délai garantit que rien n'est sauté entre deux interrogations.

Arguments

  • cursorstringfacultatif

    Le next_cursor de l'appel précédent. La première fois, commencez sans (ou avec since).

    ex. : "ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE"

  • sincestringfacultatif

    RFC 3339. Le point de départ quand vous n'avez pas encore de cursor. Ignoré si cursor est envoyé. Sans les deux, vous commencez au début des 90 jours.

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

  • kindsstring[]facultatif

    Uniquement ces types : bounce_hard, bounce_soft, blocked, complaint, dropped. Une chaîne séparée par des virgules fonctionne aussi. Sans ce paramètre, vous obtenez tous les types.

    ex. : ["bounce_hard", "complaint"]

  • limitnumberfacultatif

    Événements par appel, de 1 à 1000. Par défaut : 100.

    ex. : 100

Démarrage rapide

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

Réponse

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

Champs de la réponse

  • events

    Les événements de cet appel, du plus ancien au plus récent. Chacun contient les champs ci-dessous.

  • next_cursor

    Envoyez-le comme cursor au prochain appel. Si rien de nouveau n'est arrivé, c'est le même cursor que celui que vous avez envoyé.

  • has_more

    true lorsque d'autres événements attendent déjà : rappelez immédiatement au lieu d'attendre votre prochaine interrogation.

  • events[].email_id

    L'ID de l'e-mail (un UUID) : l'id que vous avez reçu à l'envoi, et le même id que dans Logs et les webhooks.

  • events[].kind

    Ce qui s'est passé : bounce_hard, bounce_soft, blocked, complaint ou dropped. Voir Types ci-dessous.

  • events[].source

    D'où nous l'avons appris : la réponse SMTP, un message de bounce, un feedback loop, un signalement d'abus… Voir Sources ci-dessous.

  • events[].recipient

    L'adresse à laquelle l'e-mail a été envoyé.

  • events[].from

    L'adresse de l'expéditeur.

  • events[].campaign_id

    La campagne, quand l'e-mail en fait partie.

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

    Le code renvoyé par le serveur destinataire, par exemple 550 et 5.1.1. Uniquement pour les bounces et les blocages.

  • events[].diagnostic

    La réponse complète du serveur destinataire, ou la raison donnée dans un signalement d'abus.

  • events[].reporting_mta

    Qui l'a signalé : le serveur qui a envoyé le message de bounce, l'adresse du feedback loop, ou web pour la page de signalement.

  • events[].at

    Quand cela s'est produit. ISO 8601, UTC.

Types

  • bounce_hard

    L'adresse n'existe pas ou n'accepte plus d'e-mails (5.1.x, la plupart des 5xx). Retirez-la de vos listes : renvoyer nuit à votre réputation.

  • bounce_soft

    Un problème temporaire qui ne s'est pas résolu à temps : boîte pleine (5.2.2), un 4xx dont les tentatives sont épuisées, ou l'e-mail a expiré dans la file. Vous pouvez réessayer plus tard.

  • blocked

    Le serveur destinataire a refusé le message lui-même : filtre antispam, politique, blocklist ou authentification (5.7.x). L'adresse est bonne, ne la retirez pas : corrigez ce qui a été envoyé.

  • complaint

    Le destinataire a marqué l'e-mail comme spam (feedback loop) ou l'a signalé comme abus. Arrêtez d'envoyer à cette adresse.

  • dropped

    Sendcorex ne l'a jamais envoyé : compte bloqué, plus de crédits ou adresse invalide.

Sources

  • smtp

    La réponse du serveur destinataire pendant la livraison.

  • dsn

    Un message de bounce arrivé plus tard au Return-Path, après que le serveur a d'abord accepté l'e-mail.

  • expired

    L'e-mail était toujours dans la file après 5 jours et a été abandonné.

  • retries_exhausted

    Le serveur destinataire n'a cessé de le différer et toutes les tentatives ont été utilisées.

  • outgoing

    Arrêté avant l'envoi (c'est ce que portent les événements dropped).

  • fbl_microsoft / fbl_yahoo / fbl_other

    Un signalement de spam provenant du feedback loop du fournisseur (Outlook/Hotmail, Yahoo/AOL, autres).

  • abuse_mailbox

    Quelqu'un a écrit à l'adresse d'abus du header X-Report-Abuse de l'e-mail.

  • abuse_web

    Quelqu'un a utilisé la page de signalement liée dans le header X-Report-Abuse.

Polling

Stockez le cursor quelque part qui survit à un redémarrage (une ligne en base, un fichier). À chaque cycle, lisez jusqu'à ce que has_more vaille false, traitez chaque événement et enregistrez le nouveau 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);
i

call est n'importe quel helper qui envoie { commands: [...] } en POST à /v1/feedback et renvoie results, comme dans Run Commands.

!

Ne retirez des adresses que sur bounce_hard et complaint. Un événement blocked signifie que le serveur a refusé ce message, pas que l'adresse est mauvaise.

i

Vous préférez le push ? Les webhooks bounced et fbl_complaint portent les mêmes événements au moment où ils se produisent. Le polling est le filet de sécurité quand votre endpoint était indisponible.

Filtrer par type

Avec kinds, le cursor avance quand même au-delà des événements filtrés, donc une boucle filtrée coûte autant qu'une boucle non filtrée.

Corps de la requête

{
  "commands": [
    {
      "command": "list_feedback",
      "args": {
        "since": "2026-10-01T00:00:00Z",
        "kinds": [
          "complaint"
        ]
      }
    }
  ]
}

L'événement

Événement

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

Erreurs

Les erreurs au niveau HTTP renvoient type, code et message. Les erreurs marquées CMD reviennent dans le résultat de la commande, avec HTTP 200.

  • 401INVALID_API_KEY

    L'API key n'existe pas, a été révoquée ou a été désactivée dans le dashboard.

  • 429RATE_LIMITED

    Plus de 15 requêtes/s ou 15 simultanées pour la même IP + API key. Attendez le nombre de secondes indiqué dans Retry-After.

  • CMDMISSING_SCOPE

    L'API key n'a pas `feedback:read`.

  • CMDINVALID_ARGS

    Un argument est invalide : type inconnu, `since` qui n'est pas au format RFC 3339, limit hors limites, `email_id` manquant…

  • CMDINVALID_CURSOR

    Le cursor est mal formé ou provient d'un autre compte. Recommencez sans cursor (ou avec `since`).

  • CMDINTERNAL

    Erreur serveur. Le détail n'est écrit que dans le log du serveur.