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.
https://g.sendcorex.com/v1/feedbackcommand: list_feedbackNécessite le scope feedback:read sur votre API key.
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.
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
cursorstringfacultatifLe
next_cursorde l'appel précédent. La première fois, commencez sans (ou avecsince).ex. :
"ZjowMDAwMDAwMDgzOjE3NjA2ODMxMjQwMzE6OWI3ZTRjMjE"sincestringfacultatifRFC 3339. Le point de départ quand vous n'avez pas encore de cursor. Ignoré si
cursorest envoyé. Sans les deux, vous commencez au début des 90 jours.ex. :
"2026-10-01T00:00:00Z"kindsstring[]facultatifUniquement 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
eventsLes événements de cet appel, du plus ancien au plus récent. Chacun contient les champs ci-dessous.
next_cursorEnvoyez-le comme
cursorau prochain appel. Si rien de nouveau n'est arrivé, c'est le même cursor que celui que vous avez envoyé.has_moretruelorsque d'autres événements attendent déjà : rappelez immédiatement au lieu d'attendre votre prochaine interrogation.events[].email_idL'ID de l'e-mail (un UUID) : l'
idque vous avez reçu à l'envoi, et le même id que dans Logs et les webhooks.events[].kindCe qui s'est passé :
bounce_hard,bounce_soft,blocked,complaintoudropped. Voir Types ci-dessous.events[].sourceD'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[].recipientL'adresse à laquelle l'e-mail a été envoyé.
events[].fromL'adresse de l'expéditeur.
events[].campaign_idLa campagne, quand l'e-mail en fait partie.
events[].smtp_code / events[].enhanced_codeLe code renvoyé par le serveur destinataire, par exemple
550et5.1.1. Uniquement pour les bounces et les blocages.events[].diagnosticLa réponse complète du serveur destinataire, ou la raison donnée dans un signalement d'abus.
events[].reporting_mtaQui l'a signalé : le serveur qui a envoyé le message de bounce, l'adresse du feedback loop, ou
webpour la page de signalement.events[].atQuand cela s'est produit. ISO 8601, UTC.
Types
bounce_hardL'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_softUn 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.
blockedLe 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é.
complaintLe destinataire a marqué l'e-mail comme spam (feedback loop) ou l'a signalé comme abus. Arrêtez d'envoyer à cette adresse.
droppedSendcorex ne l'a jamais envoyé : compte bloqué, plus de crédits ou adresse invalide.
Sources
smtpLa réponse du serveur destinataire pendant la livraison.
dsnUn message de bounce arrivé plus tard au Return-Path, après que le serveur a d'abord accepté l'e-mail.
expiredL'e-mail était toujours dans la file après 5 jours et a été abandonné.
retries_exhaustedLe serveur destinataire n'a cessé de le différer et toutes les tentatives ont été utilisées.
outgoingArrêté avant l'envoi (c'est ce que portent les événements
dropped).fbl_microsoft / fbl_yahoo / fbl_otherUn signalement de spam provenant du feedback loop du fournisseur (Outlook/Hotmail, Yahoo/AOL, autres).
abuse_mailboxQuelqu'un a écrit à l'adresse d'abus du header
X-Report-Abusede l'e-mail.abuse_webQuelqu'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);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.
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.
- 401
INVALID_API_KEYL'API key n'existe pas, a été révoquée ou a été désactivée dans le dashboard.
- 429
RATE_LIMITEDPlus 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.
- CMD
MISSING_SCOPEL'API key n'a pas `feedback:read`.
- CMD
INVALID_ARGSUn argument est invalide : type inconnu, `since` qui n'est pas au format RFC 3339, limit hors limites, `email_id` manquant…
- CMD
INVALID_CURSORLe cursor est mal formé ou provient d'un autre compte. Recommencez sans cursor (ou avec `since`).
- CMD
INTERNALErreur serveur. Le détail n'est écrit que dans le log du serveur.