API と MCP による配信到達性とバウンスの管理

TrekMail のダッシュボードでは、各ドメインの統計タブに二種類のバウンスデータが表示されます。

1. 30 日間の集計: 送信済み、配信済み、ソフトバウンス、ハードバウンスの件数と、配信率およびバウンス率。
2. 受信者別リスト: 最近の送信バウンス 50 件と、受信側の SMTP ステータスコードおよび応答。特定のメッセージが失敗した理由を確認できます。

どちらのデータも REST API と MCP サーバーから利用できるようになりました。エージェントはダッシュボードを開くことなく、バウンス理由の取得、レピュテーションの健全性の要約、リスト衛生管理ワークフローへのデータ提供を行えます。

公開されるデータ

いずれも domains:read が必要です（メールボックスに限定したリストでは mailboxes:read も使用できます）。読み取り専用です。冪等性キーは必要ありません。

API はダッシュボードの統計カードと同じ配信到達性データを使用するため、両方の表示は常に一致します。

REST API: 簡単な例

ドメイン集計

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 は、ダッシュボードに表示されるものと同じ三段階のシグナルです。

• good: バウンス率が 2% 未満。
• warning: バウンス率が 2% から 5% の間。
• poor: バウンス率が 5% 以上。送信リストを確認して整理してください。

forwarding_bounces_excluded は、転送に関連するバウンスのうち、率の計算から除外された件数を示します（ダッシュボードと同様に、これらは送信者リストの問題ではなくルーティングの副作用として扱われます）。

受信者別のバウンスリスト

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

クエリパラメーター

メールボックスに限定したリスト

送信者ごとのレピュテーションを調査するには、対象をひとつのメールボックスに限定します。

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

応答の形式はドメインエンドポイントと同じです。

SMTP 応答のプライバシー

TrekMail は SMTP 応答を返す前に内部診断情報を削除します。残るメッセージはダッシュボードでアカウント所有者に表示されるものと同じで、サーバー内部の情報を公開するためではなく、配信の問題を診断するためのものです。

MCP ツール

いずれのツールも REST エンドポイントと同じパラメーターを受け取ります。読み取り専用であり、メールやアカウント設定を変更しません。

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

大量送信者向けの配信到達性ヘッダー

マーケティングメールや購読型の一括メールを送信する場合、主要なメールボックスプロバイダーからワンクリック配信停止ヘッダーを求められることがあります。Google は、一括送信者の基準を超える送信者からのマーケティングメッセージと購読メッセージにこのルールを適用します。トランザクションメッセージにはワンクリックのルールを適用しません。ヘッダーを追加する方法は二通りあります。

メッセージごと（きめ細かな設定）。 headers フィールドを通じて 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"
  }
}

headers フィールドで許可されるのは、List-Unsubscribe、List-Unsubscribe-Post、Reply-To、および任意の X-* カスタム追跡ヘッダーからなる小規模な許可リストです。ヘッダーインジェクション（CR/LF）と管理対象ヘッダー（From、Subject、Date、Message-Id、Authentication-Results、DKIM-Signature など）は 422 で拒否されます。

アカウント全体（一度だけ設定）。 このアカウントからのすべての送信メッセージが自動化されている場合は、アカウントの auto_list_unsubscribe を有効にできます。有効にすると、プラットフォームは、まだこのヘッダーがないすべての送信メッセージに mailto のみの List-Unsubscribe ヘッダーを追加します。List-Unsubscribe-Post は追加されないため、この代替手段は RFC 8058 に準拠したワンクリック配信停止ではありません。プロバイダーの要件に準拠したワンクリック配信停止を実現するには、上の例のように、独自の HTTPS 配信停止エンドポイントを使用して両方のヘッダーをメッセージごとに指定してください。呼び出し元が指定したヘッダーが常に優先されます。この切り替えはデフォルトでオフであり、既存のアカウントは変更されません。

一対一の個人的なメールでは、切り替えをオフのままにしてください。このヘッダーがある場合、Gmail は送信者の横に配信停止ボタンを表示することがありますが、通常は会話には適していません。

AI エージェント向けのパターン

これらのエンドポイントから、価値の高いワークフローをいくつか構築できます。

• 週次レピュテーションダイジェスト。 毎週月曜日に、アカウントの各ドメインについて get_domain_deliverability を呼び出し、Slack または Teams に要約を投稿します。status が warning または poor のドメインだけを表示します。
• バウンスに基づくリスト衛生管理。 list_domain_bounces?type=hard&days=14 を呼び出し、recipient_email の重複を排除してから、そのアドレスを送信リストで抑制します。ハードバウンスは通常、受信者のアドレスが存在しないことを意味し、再送信は配信到達性の余力を浪費します。
• 送信者ごとの調査。 単一のメールボックスの bounce_rate が急上昇したら、そのメールボックスに対して list_mailbox_bounces を呼び出し、smtp_status_code でグループ化します。550 が急増していればアドレスリストが古くなっている可能性があり、421 が急増していれば受信メールサーバーによって送信頻度を制限された可能性があります。
• カスタマーサポートの調査。 ユーザーからメールが届かなかったという報告を受けたら、エージェントに list_domain_bounces?recipient=<their-address> を呼び出させます。SMTP 応答から、受信者の満杯になったメールボックスを空ける、受信者側のブロックを解除する、DMARC による拒否を修正するなど、次の対応が分かる場合があります。

バージョン管理

これらのエンドポイントは、v1 API の他の部分と同じバージョン管理規約に従います。追加的な変更のみを行い、v2/ 名前空間なしで互換性を損なうフィールド名の変更は行いません。