Deliverability and Bounces

TrekMail's dashboard surfaces two kinds of bounce data on every domain's Stats tab:

1. A 30-day rollup — sent, delivered, soft-bounce, hard-bounce counts plus delivery rate and bounce rate.
2. A per-recipient list — the last 50 outbound bounces with the receiver's SMTP status code and response, so you can see why each specific message failed.

Both are now available through the REST API and the MCP server. An agent can pull bounce reasons, summarise reputation health, and feed list-hygiene workflows without ever opening the dashboard.

What's exposed

All three require domains:read (or mailboxes:read for the mailbox-scoped list). Read-only. No idempotency key needed.

The deliverability rollup wraps the same cached service that powers the dashboard's stats cards, so the API and the dashboard always agree — no stale numbers, no race conditions between the two views.

REST API — quick examples

Domain rollup

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 the same three-state signal the dashboard renders:

• good — bounce rate below 2 %.
• warning — bounce rate between 2 % and 5 %.
• poor — bounce rate at or above 5 %. List hygiene work is overdue.

forwarding_bounces_excluded reports how many forwarding-related bounces were dropped from the rate calculations (consistent with the dashboard, which treats those as routing artefacts, not sender-list problems).

Per-recipient bounce list

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

Query parameters

Mailbox-scoped list

For per-sender reputation triage, scope to one mailbox:

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

Same response shape as the domain endpoint.

Privacy of SMTP responses

smtp_response strings are sanitised before exposure:

• Private RFC1918 IPs (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) are replaced with [internal].
• Multi-line SMTP transcripts are truncated to the first line.
• Internal LMTP diagnostics (Dovecot/Postfix routing metadata) are dropped.

The remaining smtp_response is exactly what the dashboard shows the account owner.

MCP tools

All three tools accept the same parameters as the REST endpoints. Read-only — no TREKMAIL_ALLOW_DESTRUCTIVE gate needed.

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

Patterns for AI agents

A few high-value flows that drop out of these endpoints:

• Weekly reputation digest. Each Monday, call get_domain_deliverability for every domain on the account and post a summary into Slack/Teams. Surface only domains where status is warning or poor.
• Bounce-driven list hygiene. Call list_domain_bounces?type=hard&days=14, deduplicate recipient_email, then suppress those addresses from your sending list. Hard bounces almost always mean the recipient address no longer exists — re-sending wastes deliverability budget.
• Per-sender triage. When a single mailbox's bounce_rate jumps, call list_mailbox_bounces on it and group by smtp_status_code. A burst of 550s means the address list went stale; a burst of 421s means the receiving MX rate-limited you.
• Customer-support investigation. When a user reports "my email didn't arrive," ask the agent to call list_domain_bounces?recipient=<their-address> — the SMTP response often tells you exactly what to fix (mailbox full, blocked by recipient, DMARC reject, etc.).

Versioning

These endpoints follow the same versioning contract as the rest of the v1 API: additive changes only, no breaking field renames without a v2/ namespace.

Related

• Spam Metrics — inbound spam protection telemetry (get_spam_metrics, get_spam_summary).
• Email Verifier — pre-send list cleaning so bounces never happen in the first place.
• API Overview — auth, scopes, rate limits, idempotency.