Journaux d'e-mails

Recherchez, filtrez et inspectez les journaux de livraison détaillés pour chaque e-mail envoyé via Mail.Land

Cette page liste uniquement les messages transactionnels : les e-mails de campagnes et d'automatisations (y compris les messages système sys_*) en sont exclus. Utilisez le point de terminaison des destinataires de campagne (voir Campagnes) pour l'historique d'envoi marketing/automatisation.

Lister les e-mails

GET https://api.mail.land/v1/transactional/logs

List emails

curl "https://api.mail.land/v1/transactional/logs?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Paramètres de requête

Paramètre	Type	Défaut	Description
`cursor`	string	-	Curseur opaque issu du `nextCursor` de la page précédente. À omettre pour la première page. Un curseur malformé ou altéré renvoie `400 INVALID_CURSOR`.
`limit`	int	20	Éléments par page
`status`	string	-	Filtrer par statut (voir ci-dessous)
`search`	string	-	Rechercher par destinataire, objet ou ID de message
`from`	datetime	Il y a 30 jours	Date de début
`to`	datetime	Maintenant	Date de fin
`refresh`	bool	false	Éviter une page obsolète : il n'y a plus de cache de comptage à contourner

Filtres de statut

Valeur	Correspond à
`queued`	En attente dans la file
`sent`	Accepté par le MTA
`deferred` ou `retrying`	Temporairement retardé
`delivered`	Livré avec succès
`bounced`	Rebond permanent
`failed`	Erreur système ou rebond administratif
`opened`	Le destinataire a ouvert l'e-mail
`clicked`	Le destinataire a cliqué sur un lien
`complained`	Le destinataire a signalé un spam

Email logs response

{
  "items": [
    {
      "messageId": "t_a1b2c3d4e5f6",
      "recipient": "[email protected]",
      "subject": "Your order has shipped",
      "status": "delivered",
      "sentAt": "2026-02-17T12:34:56Z",
      "deliveredAt": "2026-02-17T12:34:58Z",
      "openedAt": "2026-02-17T13:15:00Z",
      "clickedAt": null,
      "bounceReason": null,
      "openCount": 2,
      "clickCount": 0
    },
    {
      "messageId": "t_d4e5f6a1b2c3",
      "recipient": "[email protected]",
      "subject": "Invoice #1234",
      "status": "bounced",
      "sentAt": "2026-02-17T12:30:00Z",
      "deliveredAt": null,
      "openedAt": null,
      "clickedAt": null,
      "bounceReason": "550 5.1.1 Mailbox not found",
      "openCount": 0,
      "clickCount": 0
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Priorité des statuts

Le champ status reflète l'événement de la plus haute priorité pour chaque e-mail :

complained (le plus élevé)
clicked
opened
Statut de livraison : queued → sent → deferred → delivered → bounced → failed

Par exemple, si un e-mail a été livré puis ouvert, le statut affiche opened.

Une plage de dates par défaut de 30 jours est appliquée pour des raisons de performances. Le paramètre de recherche filtre par e-mail du destinataire, ligne d'objet ou ID de message (insensible à la casse).

Statistiques des journaux

Obtenez des statistiques agrégées pour vos journaux d'e-mails :

GET https://api.mail.land/v1/transactional/logs/stats

Get log stats

curl "https://api.mail.land/v1/transactional/logs/stats" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Paramètre	Type	Défaut	Description
`from`	datetime	Il y a 7 jours	Date de début
`to`	datetime	Maintenant	Date de fin
`emailType`	int	-	`0` = Transactionnel, `1` = Marketing. Omettre ce paramètre couvre tous les types d'e-mails : contrairement à « Lister les e-mails » ci-dessus, qui ne couvre que les transactionnels.
`refresh`	bool	false	Contourner le cache

Log stats response

{
  "total": 4750,
  "accepted": 4750,
  "sent": 4700,
  "delivered": 4680,
  "opened": 1498,
  "clicked": 195,
  "bounced": 38,
  "complained": 1,
  "failed": 12,
  "queued": 20,
  "deliveryRate": 99.57,
  "openRate": 32.01,
  "clickRate": 13.02,
  "bounceRate": 0.81,
  "complaintRate": 0.021,
  "source": "clickhouse",
  "queryTimeMs": 32
}

Calculs des taux :

Taux	Formule
`deliveryRate`	`delivered / sent * 100`
`openRate`	`opened / delivered * 100`
`clickRate`	`clicked / delivered * 100`
`bounceRate`	`bounced / sent * 100`
`complaintRate`	`complained / sent * 100` (3 décimales)

Les en-têtes de réponse indiquent le statut du cache :

En-tête	Valeurs
`X-Cache`	`HIT`, `MISS` ou `FRESH`
`X-Stats-Source`	`cache` ou `clickhouse`
`Cache-Control`	Toujours `no-store, no-cache, must-revalidate`

Détail d'un e-mail

Obtenez les détails complets d'un e-mail spécifique, y compris la chronologie des événements :

GET https://api.mail.land/v1/transactional/logs/{messageId}

Get email detail

curl https://api.mail.land/v1/transactional/logs/t_a1b2c3d4e5f6 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Email detail response

{
  "messageId": "t_a1b2c3d4e5f6",
  "recipient": "[email protected]",
  "fromEmail": "[email protected]",
  "subject": "Your order has shipped",
  "status": "opened",
  "sentAt": "2026-02-17T12:34:56Z",
  "deliveredAt": "2026-02-17T12:34:58Z",
  "openedAt": "2026-02-17T13:15:00Z",
  "clickedAt": null,
  "createdAt": "2026-02-17T12:34:55Z",
  "bounceReason": null,
  "bounceCategory": null,
  "ipAddress": null,
  "retryCount": 0,
  "smtpResponse": "250 2.0.0 OK",
  "openCount": 2,
  "clickCount": 0,
  "htmlContent": "<html>...</html>",
  "textContent": "Your order has shipped...",
  "events": [
    {
      "eventType": "delivered",
      "timestamp": "2026-02-17T12:34:58Z",
      "ipAddress": null,
      "userAgent": null,
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": "250 2.0.0 OK",
      "deviceType": null,
      "browser": null,
      "country": null,
      "city": null
    },
    {
      "eventType": "opened",
      "timestamp": "2026-02-17T13:15:00Z",
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": null,
      "deviceType": "desktop",
      "browser": "Chrome",
      "country": "US",
      "city": "San Francisco"
    },
    {
      "eventType": "opened",
      "timestamp": "2026-02-17T14:30:00Z",
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": null,
      "deviceType": "mobile",
      "browser": "Safari",
      "country": "US",
      "city": "San Francisco"
    }
  ]
}

Le tableau events est fourni par ClickHouse et trié par horodatage. Si ClickHouse est temporairement indisponible, le détail de l'e-mail est quand même retourné depuis PostgreSQL mais events sera un tableau vide.

Champs des événements

Champ	Description
`eventType`	`delivered`, `opened`, `clicked`, `bounced`, `complained`, ainsi que `accepted`, `sent`, `deferred`, `admin_bounce`, `oob_bounce`, `expired`
`timestamp`	Quand l'événement s'est produit (UTC)
`ipAddress`	IP du client (pour les ouvertures/clics)
`userAgent`	Chaîne user agent du client
`linkUrl`	URL cliquée (pour les événements `clicked`)
`bounceType`	`hard`, `soft` ou `unknown` (pour les événements `bounced`)
`bounceReason`	Réponse SMTP (pour les événements `bounced`)
`smtpResponse`	Réponse du serveur distant (pour les événements `delivered`)
`deviceType`	`desktop`, `mobile` ou `tablet`
`browser`	Nom du navigateur (Chrome, Safari, Firefox, etc.)
`country`	Code pays ISO
`city`	Nom de la ville

Relancer un e-mail échoué

Relancer la livraison d'un e-mail rejeté ou échoué :

POST https://api.mail.land/v1/transactional/logs/{messageId}/retry

Retry failed email

curl -X POST https://api.mail.land/v1/transactional/logs/t_a1b2c3d4e5f6/retry \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Le message doit avoir le statut Bounced ou Failed, et le destinataire ne doit pas être supprimé.

Statut	Code	Description
`200`	-	Relance acceptée
`400`	`INVALID_REQUEST`	L'e-mail n'est pas rejeté ou échoué
`400`	`RECIPIENT_SUPPRESSED`	Le destinataire est sur la liste de suppression
`404`	`RESOURCE_NOT_FOUND`	Message introuvable : pas `EMAIL_NOT_FOUND`
`422`	`DOMAIN_NOT_VERIFIED`	Le domaine d'envoi n'est plus vérifié
`429`	`MARKETING_PAUSED`	L'envoi marketing est actuellement en pause pour cet espace de travail
`422`	`RETRY_ATTACHMENTS_UNAVAILABLE`	Le message avait des pièces jointes qui ne peuvent plus être récupérées ; renvoyez-le avec ses pièces jointes
`422`	`RETRY_ATTACHMENTS_UNKNOWN`	Le message a été envoyé avant l'enregistrement des pièces jointes, une nouvelle tentative ne peut donc pas les garantir ; renvoyez-le
`429`	`PLATFORM_CAPACITY_PROTECTION`	Les nouveaux envois sont brièvement suspendus pour protéger la capacité de la plateforme ; rien n'a été modifié, réessayez sous peu
`503`	`RETRY_ATTACHMENT_STORAGE_UNAVAILABLE`	Les pièces jointes n'ont pas pu être lues pour l'instant ; rien n'a été modifié, réessayez sous peu

La relance crée un nouveau travail d'e-mail avec le contenu original et le met en file d'attente pour la livraison. Les copies relancées sont envoyées sans suivi d'ouverture/de clic.

Étapes suivantes

Vue d'ensemble des analytiques : résumés d'événements agrégés et taux
Analytiques avancées : ventilations géographiques, par appareil et par heure de la journée
Rebonds : comprendre la gestion des rebonds et les relances

Journaux d'e-mails

Lister les e-mailsCopier le lien de la section

Paramètres de requêteCopier le lien de la section

Filtres de statutCopier le lien de la section

Priorité des statutsCopier le lien de la section

Statistiques des journauxCopier le lien de la section

Détail d'un e-mailCopier le lien de la section

Champs des événementsCopier le lien de la section

Relancer un e-mail échouéCopier le lien de la section

Étapes suivantesCopier le lien de la section

Sur cette page