Logs : Lecture

Lister les logs

Vos logs de livraison, du plus récent au plus ancien, jusqu'à 50 par page. Filtrez par statut, destinataire, objet, domaine, expéditeur et date, dans n'importe quelle combinaison.

POSThttps://g.sendcorex.com/v1/logscommand: list_logs
i

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

i

Les filtres se combinent avec AND. Sans after, vous obtenez les 60 derniers jours, soit la durée de conservation des logs.

i

Les e-mails de warm-up n'apparaissent jamais ici, et le corps de l'e-mail ne fait jamais partie d'une liste. Utilisez Get Logs avec include_content pour en lire un.

Arguments

  • statusstring | string[]facultatif

    delivered, bounced, spam, rate_limited ou not_sent, ou une liste de ces valeurs. Sans ce paramètre, vous obtenez les cinq.

    ex. : "bounced"

  • recipientstringfacultatif

    Une adresse e-mail complète. La casse et les espaces autour sont ignorés.

    ex. : "ana@acme.com"

  • subjectstringfacultatif

    Mots de l'objet. Des mots entiers, et tous doivent être présents : order shipped trouve "Your order #1042 has shipped", ord non. Les accents et la casse sont ignorés.

    ex. : "order shipped"

  • searchstringfacultatif

    Texte libre, pour un champ de recherche. Avec un @, c'est un destinataire ; sinon, ce sont des mots de l'objet.

    ex. : "ana@acme.com"

  • domainstringfacultatif

    Le domaine du destinataire, exact.

    ex. : "gmail.com"

  • fromstringfacultatif

    L'adresse de l'expéditeur, exacte.

    ex. : "noreply@yourdomain.com"

  • afterstring | numberfacultatif

    Uniquement les logs envoyés à ce moment ou après. ISO 8601, YYYY-MM-DD (minuit UTC) ou epoch en millisecondes. Par défaut : il y a 60 jours.

    ex. : "2026-10-01"

  • beforestring | numberfacultatif

    Uniquement les logs envoyés avant ce moment. Mêmes formats.

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

  • limitnumberfacultatif

    Taille de la page, de 1 à 50. Par défaut : 50.

    ex. : 50

  • cursorstringfacultatif

    Le next_cursor de la page précédente. Envoyez-le avec les mêmes filtres.

Démarrage rapide

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/logs',
  {
    commands: [
      {
        command: "list_logs",
        args: {
          status: "bounced",
          after: "2026-10-01",
          limit: 50
        }
      }
    ]
  },
  { 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_logs",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 18,
      "data": {
        "logs": [
          {
            "id": "9b7e4c21-0d3a-4e8f-a6b1-5c2d7e9f1a30",
            "to": "old.address@gmail.com",
            "from": "noreply@yourdomain.com",
            "domain": "gmail.com",
            "from_domain": "yourdomain.com",
            "subject": "Your order #1042 has shipped",
            "status": "bounced",
            "status_code": 6,
            "response": "550 5.1.1 The email account that you tried to reach does not exist.",
            "message": null,
            "blocked": false,
            "block_reason": null,
            "retries": 0,
            "tracking_id": "7CK-JDL-Z2M-20261017",
            "sent_at": "2026-10-17T05:58:44.031Z",
            "updated_at": "2026-10-17T05:58:45.600Z"
          }
        ],
        "count": 1,
        "has_more": true,
        "next_cursor": "MDAwMDAwMDA4MzowOjgyMzkzMTU5OTg3OTU6M2YyYTFi",
        "partial": false,
        "total": 1240,
        "total_exact": true
      }
    }
  ]
}

Champs de la réponse

  • logs

    Les logs de cette page, du plus récent au plus ancien. Chacun contient les champs ci-dessous.

  • count

    Le nombre de logs dans cette page.

  • has_more / next_cursor

    Tant que has_more vaut true, envoyez next_cursor comme cursor avec les mêmes filtres.

  • partial

    true lorsque la recherche a atteint sa limite de temps avant de remplir la page. La page peut contenir moins de logs, voire zéro, et next_cursor reprend là où elle s'est arrêtée.

  • total / total_exact

    Le nombre de logs qui correspondent aux filtres, sur la première page uniquement (la requête sans cursor). Sur les pages suivantes, les deux valent null : gardez la première valeur. total n'est un nombre que lorsqu'il est exact (total_exact: true). Avec total: null et total_exact: false, il y en a trop pour les compter ; avec les deux à null, la recherche ne peut pas être comptée (par exemple un objet sans mot indexable). Dans tous les cas, continuez à paginer avec has_more.

  • logs[].id

    L'ID de l'e-mail (un UUID). C'est l'id que vous recevez à l'envoi, et celui que vous passez à Get Logs.

  • logs[].to / logs[].domain

    Le destinataire et le domaine du destinataire.

  • logs[].from_domain

    Le domaine de l'expéditeur (la partie après @ dans from).

  • logs[].from

    L'adresse de l'expéditeur.

  • logs[].subject

    La ligne d'objet.

  • logs[].status

    delivered, bounced, spam, rate_limited ou not_sent. status_code est la même chose sous forme de nombre.

  • logs[].response

    Ce que le serveur destinataire a répondu, par exemple 250 2.0.0 OK ou la raison du bounce 550.

  • logs[].message

    Un détail supplémentaire de Sendcorex sur la livraison, le cas échéant.

  • logs[].blocked / logs[].block_reason

    true lorsque Sendcorex n'a pas envoyé à ce destinataire (supprimé ou restreint), et pourquoi.

  • logs[].retries

    Le nombre de nouvelles tentatives de livraison.

  • logs[].tracking_id

    L'id interne de la livraison. Les webhooks de bounce et de plainte portent la même valeur.

  • logs[].sent_at / logs[].updated_at

    Quand l'e-mail a été envoyé et quand son statut a changé pour la dernière fois. ISO 8601, UTC.

Statuts

  • delivered

    Le serveur destinataire a accepté l'e-mail.

  • bounced

    Le serveur destinataire l'a rejeté définitivement : l'adresse n'existe pas, le domaine n'accepte pas d'e-mails…

  • spam

    Le serveur destinataire l'a refusé comme spam.

  • rate_limited

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

  • not_sent

    Non envoyé à cause de votre compte (par exemple, plus de crédits, compte bloqué ou restreint, domaine d'expéditeur listé chez Spamhaus ou sans DKIM, ou From invalide). Ce n'est pas un rebond. La raison exacte est dans response.

i

Les e-mails qui attendent encore une nouvelle tentative ne sont pas encore ici : ils apparaissent lorsqu'ils atteignent l'un de ces cinq statuts.

Pagination

Continuez tant que has_more vaut true. Ne vous arrêtez pas sur une page courte ou vide : lorsque partial vaut true, la recherche a manqué de temps sur cet appel, pas de logs.

Node.js

const logs = [];
let cursor;

do {
  const [result] = await call({
    command: 'list_logs',
    args: { status: 'bounced', after: '2026-10-01', ...(cursor ? { cursor } : {}) },
  });
  logs.push(...result.data.logs);
  cursor = result.data.has_more ? result.data.next_cursor : null;
} while (cursor);
i

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

!

Un cursor ne fonctionne qu'avec les filtres dont il est issu. Changez un filtre et vous obtenez INVALID_CURSOR : recommencez sans cursor.

Suivre les nouveaux bounces

Pour réagir aux bounces (ou à autre chose) dès qu'ils se produisent, faites du polling avec after réglé sur le sent_at le plus récent que vous avez vu. after inclut ce moment, donc le dernier log revient une fois de plus : ignorez les ids que vous avez déjà.

Node.js

const seen = new Set();
let since = new Date(Date.now() - 3600_000).toISOString(); // start with the last hour

setInterval(async () => {
  let cursor;
  do {
    const [result] = await call({
      command: 'list_logs',
      args: { status: 'bounced', after: since, ...(cursor ? { cursor } : {}) },
    });
    for (const log of result.data.logs) {
      if (seen.has(log.id)) continue;
      seen.add(log.id);
      if (log.sent_at > since) since = log.sent_at;
      await removeFromMyList(log.to, log.response); // your code
    }
    cursor = result.data.has_more ? result.data.next_cursor : null;
  } while (cursor);
}, 10_000);
i

Les lectures identiques à moins de 1,5 seconde d'intervalle partagent un même résultat, donc plusieurs workers qui interrogent la même chose n'ajoutent pas de charge. Si vous avez besoin de l'événement au moment où il se produit, utilisez plutôt le webhook bounced.

Plus d'exemples

Corps de la requête

{
  "commands": [
    {
      "command": "list_logs",
      "id": "ana",
      "args": {
        "recipient": "ana@acme.com"
      }
    },
    {
      "command": "list_logs",
      "id": "shipped",
      "args": {
        "subject": "order shipped",
        "status": "delivered",
        "after": "2026-10-10"
      }
    },
    {
      "command": "list_logs",
      "id": "gmail_spam",
      "args": {
        "domain": "gmail.com",
        "status": [
          "spam",
          "bounced"
        ]
      }
    },
    {
      "command": "list_logs",
      "id": "one_day",
      "args": {
        "after": "2026-10-16",
        "before": "2026-10-17",
        "limit": 20
      }
    }
  ]
}

Le log

List Logs et Get Logs renvoient la même structure.

Log

{
  "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
  "to": "ana@acme.com",
  "from": "noreply@yourdomain.com",
  "domain": "acme.com",
  "from_domain": "yourdomain.com",
  "subject": "Your order #1042 has shipped",
  "status": "delivered",
  "status_code": 2,
  "response": "250 2.0.0 OK 1760684401 a1si123456",
  "message": null,
  "blocked": false,
  "block_reason": null,
  "retries": 0,
  "tracking_id": "7CK-JDL-Y1L-20261017",
  "sent_at": "2026-10-17T06:00:01.204Z",
  "updated_at": "2026-10-17T06:00:02.913Z"
}

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 `logs:read`.

  • CMDINVALID_ARGS

    Un argument est invalide : statut inconnu, destinataire qui n'est pas un e-mail complet, limit hors limites, id qui n'est pas un UUID, after postérieur à before…

  • CMDINVALID_CURSOR

    Le cursor est mal formé, ou il provient d'une autre recherche ou d'un autre compte. Recommencez sans cursor.

  • CMDINTERNAL

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