Délivrabilité et rejets avec API et MCP

Le tableau de bord TrekMail présente deux types de données sur les rejets dans l’onglet Statistiques de chaque domaine :

1. Un bilan sur 30 jours : nombres de messages envoyés, livrés, temporairement rejetés et définitivement rejetés, ainsi que les taux de livraison et de rejet.
2. Une liste par destinataire : les 50 derniers rejets sortants avec le code d’état et la réponse SMTP du serveur destinataire, afin de comprendre l’échec d’un message précis.

Les deux sont désormais accessibles par REST API et par le serveur MCP. Un agent peut récupérer les motifs de rejet, résumer l’état de la réputation et alimenter les processus d’hygiène des listes sans jamais ouvrir le tableau de bord.

Données disponibles

Les trois nécessitent domains:read (ou mailboxes:read pour la liste limitée à la boîte). Lecture seule. Aucune clé d’idempotence n’est nécessaire.

L’API utilise les mêmes données de délivrabilité que les cartes de statistiques du tableau de bord, afin que les deux vues restent cohérentes.

REST API : exemples rapides

Bilan du domaine

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/deliverability?days=30" | jq .

{
  "data": {
    "from": "2026-04-26T00:00:00+00:00",
    "to":   "2026-05-26T23:59:59+00:00",
    "sent": 4180,
    "delivered": 4112,
    "soft_bounce": 22,
    "hard_bounce": 46,
    "forwarding_bounces_excluded": 7,
    "delivery_rate": 0.9837,
    "bounce_rate": 0.0163,
    "status": "good"
  }
}

status est le même indicateur à trois états que celui affiché par le tableau de bord :

• good : taux de rejet inférieur à 2 %.
• warning : taux de rejet compris entre 2 % et 5 %.
• poor : taux de rejet supérieur ou égal à 5 %. Vérifiez et nettoyez la liste d’envoi.

forwarding_bounces_excluded indique le nombre de rejets liés au transfert qui ont été exclus du calcul des taux (comme dans le tableau de bord, où ils sont considérés comme des incidents de routage et non comme des problèmes de liste d’expéditeur).

Liste des rejets par destinataire

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/bounces?days=7&type=hard&limit=50" | jq .

{
  "data": [
    {
      "id": 994821,
      "occurred_at": "2026-05-26T18:14:02+00:00",
      "recipient_email": "lost@example.com",
      "event_type": "hard_bounce",
      "smtp_status_code": "550",
      "smtp_response": "5.1.1 The email account that you tried to reach does not exist.",
      "mailbox_id": 7741,
      "domain_id": 123
    }
  ],
  "pagination": { "total": 17, "limit": 50, "offset": 0 }
}

Paramètres de requête

Liste limitée à la boîte

Pour analyser la réputation de chaque expéditeur, limitez la requête à une boîte :

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/mailboxes/7741/bounces?days=14&type=soft" | jq .

La réponse a la même structure que celle de l’endpoint de domaine.

Confidentialité des réponses SMTP

TrekMail supprime les informations de diagnostic internes avant de renvoyer une réponse SMTP. Le message restant est le même que celui présenté au propriétaire du compte dans le tableau de bord. Il sert à diagnostiquer la livraison, et non à exposer le fonctionnement interne du serveur.

Outils MCP

Les trois outils acceptent les mêmes paramètres que les endpoints REST. Ils sont en lecture seule et ne modifient ni les messages ni les paramètres du compte.

get_domain_deliverability

{
  "name": "get_domain_deliverability",
  "arguments": {
    "domain_id": 123,
    "days": 30
  }
}

list_domain_bounces

{
  "name": "list_domain_bounces",
  "arguments": {
    "domain_id": 123,
    "type": "hard",
    "days": 7,
    "limit": 100
  }
}

list_mailbox_bounces

{
  "name": "list_mailbox_bounces",
  "arguments": {
    "mailbox_id": 7741,
    "recipient": "@example.com",
    "limit": 50
  }
}

En-têtes de délivrabilité pour les envois groupés

Si vous envoyez des messages marketing ou groupés sur abonnement, les principaux fournisseurs de boîtes peuvent imposer des en-têtes de désabonnement en un clic. Google applique cette règle aux messages marketing et sur abonnement des expéditeurs qui dépassent son seuil d’envoi groupé. La règle en un clic ne s’applique pas aux messages transactionnels. Deux méthodes permettent d’ajouter ces en-têtes :

Par message (précis). Transmettez-les dans le champ headers de POST /api/v1/messages/send :

{
  "to": ["recipient@example.com"],
  "subject": "...",
  "body": {"text": "..."},
  "headers": {
    "List-Unsubscribe": "<mailto:bounces@mydomain.com?subject=unsubscribe>, <https://mydomain.com/u/abc123>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

Le champ headers accepte une petite liste d’éléments autorisés : List-Unsubscribe, List-Unsubscribe-Post, Reply-To et tout en-tête de suivi personnalisé X-*. L’injection d’en-têtes (CR/LF) et les en-têtes gérés (From, Subject, Date, Message-Id, Authentication-Results, DKIM-Signature, etc.) sont refusés avec 422.

Pour tout le compte (une seule configuration). Si tous les messages sortants de ce compte sont automatisés, vous pouvez activer auto_list_unsubscribe sur le compte. Lorsqu’elle est activée, la plateforme ajoute un en-tête List-Unsubscribe avec mailto uniquement à chaque message sortant qui n’en possède pas. Elle n’ajoute pas List-Unsubscribe-Post; cette solution de repli n’offre donc pas le désabonnement en un clic de la RFC 8058. Pour respecter les exigences des fournisseurs, transmettez les deux en-têtes par message avec votre propre endpoint HTTPS de désabonnement, comme dans l’exemple ci-dessus. Les en-têtes fournis par l’appelant sont toujours prioritaires. L’option est désactivée par défaut et les comptes existants restent inchangés.

Pour les messages personnels individuels, laissez l’option désactivée. Gmail peut afficher un bouton Se désabonner à côté de l’expéditeur lorsque cet en-tête est présent, ce qui ne convient généralement pas à une conversation.

Modèles pour les agents d’IA

Voici quelques processus utiles permis par ces endpoints :

• Bilan hebdomadaire de réputation. Chaque lundi, appelez get_domain_deliverability pour chaque domaine du compte et publiez un résumé dans Slack/Teams. Signalez uniquement les domaines dont le status est warning ou poor.
• Hygiène de liste guidée par les rejets. Appelez list_domain_bounces?type=hard&days=14, dédupliquez recipient_email, puis excluez ces adresses de votre liste d’envoi. Un rejet définitif indique généralement que l’adresse du destinataire n’existe plus; renvoyer des messages gaspille votre marge de délivrabilité.
• Analyse par expéditeur. Lorsque le bounce_rate d’une boîte augmente, appelez list_mailbox_bounces pour celle-ci et regroupez les résultats par smtp_status_code. Une série de codes 550 peut indiquer que la liste d’adresses est obsolète; une série de codes 421 peut indiquer que le serveur destinataire limite votre débit.
• Enquête du service client. Lorsqu’un utilisateur signale qu’un message n’est pas arrivé, demandez à l’agent d’appeler list_domain_bounces?recipient=<their-address>. La réponse SMTP peut indiquer la prochaine action, par exemple une boîte destinataire pleine, un blocage par le destinataire ou un rejet DMARC.

Gestion des versions

Ces endpoints suivent le même contrat de version que le reste de l’API v1 : uniquement des changements additifs, aucun changement incompatible de nom de champ sans espace de noms v2/.

Articles associés

• Mesures du spam : télémétrie de protection contre le spam entrant (get_spam_metrics, get_spam_summary).
• Vérificateur d’adresses e-mail : nettoyage de la liste avant l’envoi afin d’éviter les rejets.
• Présentation de l’API : authentification, portées, limites de débit et idempotence.