Afleverbaarheid en bounces via API en MCP

Het dashboard van TrekMail toont twee soorten bouncegegevens op het tabblad Statistieken van elk domein:

1. Een overzicht van 30 dagen: aantallen verzonden en afgeleverde berichten en zachte en harde bounces, plus afleverings- en bouncepercentages.
2. Een lijst per ontvanger: de laatste 50 uitgaande bounces met de SMTP-statuscode en het antwoord van de ontvangende server, zodat je kunt zien waarom een specifiek bericht niet is afgeleverd.

Beide zijn nu beschikbaar via de REST API en de MCP-server. Een agent kan bounceredenen ophalen, de reputatiestatus samenvatten en workflows voor lijsthygiëne voeden zonder ooit het dashboard te openen.

Wat beschikbaar is

Alle drie vereisen domains:read (of mailboxes:read voor de lijst die tot een mailbox is beperkt). Alleen-lezen. Er is geen idempotentiesleutel nodig.

De API gebruikt dezelfde afleverbaarheidsgegevens als de statistiekkaarten in het dashboard, zodat beide weergaven gelijk blijven.

REST API: snelle voorbeelden

Domeinoverzicht

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 is hetzelfde signaal met drie statussen dat het dashboard weergeeft:

• good: bouncepercentage lager dan 2%.
• warning: bouncepercentage tussen 2% en 5%.
• poor: bouncepercentage van 5% of hoger. Controleer en reinig de verzendlijst.

forwarding_bounces_excluded geeft aan hoeveel bounces door doorsturen uit de percentageberekeningen zijn verwijderd (in overeenstemming met het dashboard, dat deze als routeringsartefacten behandelt en niet als problemen met de afzenderlijst).

Bouncelijst per ontvanger

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

Queryparameters

Lijst beperkt tot mailbox

Beperk de aanvraag tot één mailbox om de reputatie per afzender te onderzoeken:

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

Het antwoord heeft dezelfde structuur als bij het domeinendpoint.

Privacy van SMTP-antwoorden

TrekMail verwijdert interne diagnostische informatie voordat een SMTP-antwoord wordt geretourneerd. Het resterende bericht is hetzelfde als het bericht dat de accounteigenaar in het dashboard ziet en is bedoeld om afleveringsproblemen te diagnosticeren, niet om interne serverinformatie bloot te leggen.

MCP-tools

Alle drie de tools accepteren dezelfde parameters als de REST-endpoints. Ze zijn alleen-lezen en wijzigen geen e-mail- of accountinstellingen.

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

Afleverbaarheidsheaders voor bulkafzenders

Als je marketingberichten of bulkmail met een abonnement verzendt, kunnen grote mailboxproviders headers vereisen waarmee de ontvanger zich met één klik kan afmelden. Google past deze regel toe op marketing- en abonnementsberichten van afzenders die de drempel voor bulkafzenders overschrijden; de regel voor één klik geldt niet voor transactionele berichten. Je kunt de headers op twee manieren toevoegen:

Per bericht (gedetailleerd). Geef ze door via het veld headers van 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"
  }
}

Het veld headers accepteert een kleine lijst met toegestane waarden: List-Unsubscribe, List-Unsubscribe-Post, Reply-To en elke aangepaste trackingheader van het type X-*. Headerinjectie (CR/LF) en beheerde headers (From, Subject, Date, Message-Id, Authentication-Results, DKIM-Signature enzovoort) worden geweigerd met 422.

Voor het hele account (eenmalig instellen). Als elk uitgaand bericht van dit account geautomatiseerd is, kun je auto_list_unsubscribe voor het account inschakelen. Als deze optie is ingeschakeld, voegt het platform een List-Unsubscribe-header met alleen een mailto-adres toe aan elk uitgaand bericht dat er nog geen heeft. Het voegt geen List-Unsubscribe-Post toe, dus deze terugvaloptie biedt geen afmelding met één klik volgens RFC 8058. Voor een afmelding met één klik die aan de eisen van providers voldoet, geef je beide headers per bericht op met je eigen HTTPS-afmeldendpoint, zoals in het voorbeeld hierboven. Door de aanroeper opgegeven headers krijgen altijd voorrang. De schakelaar staat standaard UIT en bestaande accounts blijven ongewijzigd.

Laat de schakelaar uit voor persoonlijke één-op-éénmail. Gmail kan naast de afzender een knop Afmelden tonen als deze header aanwezig is, wat meestal niet passend is voor een gesprek.

Patronen voor AI-agents

Deze endpoints maken enkele waardevolle workflows mogelijk:

• Wekelijks reputatieoverzicht. Roep elke maandag get_domain_deliverability aan voor elk domein van het account en plaats een samenvatting in Slack of Teams. Toon alleen domeinen waarvan status gelijk is aan warning of poor.
• Lijsthygiëne op basis van bounces. Roep list_domain_bounces?type=hard&days=14 aan, verwijder dubbele waarden van recipient_email en sluit die adressen vervolgens uit van je verzendlijst. Harde bounces betekenen meestal dat het adres van de ontvanger niet meer bestaat en opnieuw verzenden verspilt je afleverbaarheidsmarge.
• Onderzoek per afzender. Als de bounce_rate van één mailbox plotseling stijgt, roep je daarvoor list_mailbox_bounces aan en groepeer je de resultaten op smtp_status_code. Een piek in 550-codes kan betekenen dat de adreslijst verouderd is; een piek in 421-codes kan betekenen dat de ontvangende mailserver je snelheid heeft beperkt.
• Onderzoek door de klantenservice. Als een gebruiker meldt dat een e-mail niet is aangekomen, laat je de agent list_domain_bounces?recipient=<their-address> aanroepen. Het SMTP-antwoord kan de volgende actie aangeven, zoals ruimte maken in een volle mailbox van de ontvanger, een blokkade bij de ontvanger opheffen of een DMARC-weigering corrigeren.

Versiebeheer

Deze endpoints volgen hetzelfde versiecontract als de rest van de v1 API: alleen aanvullende wijzigingen en geen incompatibele veldhernoemingen zonder een v2/-namespace.

Gerelateerd

• Spamstatistieken: telemetrie voor bescherming tegen inkomende spam (get_spam_metrics, get_spam_summary).
• E-mailverificatie: reiniging van de lijst vóór verzending, zodat bounces niet ontstaan.
• API-overzicht: authenticatie, scopes, snelheidslimieten en idempotentie.