API と MCP による差出人アドレス設定

TrekMail では、異なる認証情報と権限を使う 2 つの処理を分離しています。

1. ダッシュボード/Ops インターフェースは、再利用可能な SMTP プロファイルとドメインルーティングを管理します。tm_live_ トークンを使用し、smtp:read または smtp:write が必要です。
2. ウェブメール/メッセージ インターフェースは、1 つのメールボックスと 1 つの接続済み受信トレイで利用できる差出人アドレスを管理します。tm_msg_ トークンを使用し、messages:read、messages:write、または messages:send が必要です。

これは意図的な設計です。メールボックストークンは、すでに許可された送信ルートを選択できますが、SMTP 認証情報を公開したり、別のアカウントのインフラストラクチャを管理したりすることはできません。

概要

• external_account_id だけで送信すると、受信者には接続済みアカウント自身のアドレスが表示され、そのアカウント自身の SMTP サーバーが使用されます。
• ソースに紐づいた identity_id も指定して送信すると、受信者にはその ID のビジネスアドレスが表示されます。TrekMail はその ID に割り当てられたドメインルートまたは保存済み SMTP プロファイルを使用し、接続済み受信トレイに送信済みコピーを保存します。
• Starter では、ウェブメールから設定して使用できます。Pro と Agency では、API または MCP による自動化も可能です。Nano には接続済みアカウントの枠がありません。

利用できる API と MCP ツールは、製品とともに進化します。差出人機能は SMTP とメッセージのツール群を使用し、各接続にはプラン、スコープ、承認済み権限で許可されたサブセットのみが表示されます。

ルーティングモデル

external_account_id を identity_id なしで送信すると、TrekMail はその外部アカウント自身の SMTP サーバーを通じ、そのアカウント自身のアドレスを使って送信します。

両方の値を送信すると、TrekMail は外部アカウントを受信トレイ/送信済みの保存先、ID を表示される差出人 + SMTP ルートとして扱います。

connected Gmail inbox
  + Send As identity sales@example.com
  + identity route: domain or saved SMTP profile
  = recipients see sales@example.com
    mail is delivered through the identity route
    the Sent copy is appended to that Gmail account

ID と外部アカウントは互いに紐づけられている必要があります。ソースを省略するか、別のメールボックスの ID を指定すると、422 identity_unavailable が返されます。

1. ダッシュボード API で SMTP を確認または設定する

Ops トークンを使用します。

プロファイルの読み取りでパスワードが返されることはありません。エージェントは使用状況 endpoint を使って、共有プロファイルを編集または削除する前に影響を安全に説明できます。

MCP ツール：get_domain_smtp、set_domain_smtp、list_domain_smtp_profiles、get_domain_smtp_profile_usage、create_domain_smtp_profile、update_domain_smtp_profile、delete_domain_smtp_profile、test_domain_smtp、get_domain_smtp_test_status、get_account_smtp_default、set_account_smtp_default。

2. 対象の受信トレイのアドレスを一覧表示する

メッセージトークンを使用します。

GET /api/v1/messages/identities?external_account_id=42
Authorization: Bearer tm_msg_...

応答にはソース固有の identities、設定済みのすべての external_identities、sending_addresses、利用可能な send_as_domains、メールボックスの reply_from_policy、さらにアカウント所有者のメールボックスに限り、直接選択できる保存済みの smtp_profiles が含まれます。

MCP：list_identities を external_account_id とともに呼び出します。

ホステッド MCP とローカル stdio

メッセージツールには、トランスポートに関する重要な違いが 1 つあります。

• ホステッド HTTP MCP (OAuth)：すべてのメッセージツール呼び出しで mailbox_id も渡します。ホステッドサーバーはこれを使用し、対象メールボックス専用の有効期間が短いメッセージトークンを発行します。たとえば、list_identities を { "mailbox_id": 7, "external_account_id": 42 } とともに呼び出します。
• セルフホステッド stdio MCP (tm_msg_)：mailbox_id を渡さないでください。静的メッセージトークンはすでに 1 つのメールボックスに紐づいているため、ツールスキーマに必要なのは external_account_id だけです。

external_account_id が mailbox_id の代わりになることはありません。前者は、すでに許可されたメールボックス内の接続済み受信トレイを選択します。ダッシュボードの SMTP ツールは引き続きアカウントに限定され、どちらのトランスポートでも mailbox_id を受け取りません。

3. 差出人 ID を作成する

POST /api/v1/messages/identities
Authorization: Bearer tm_msg_...
Idempotency-Key: send-as-sales-v1
Content-Type: application/json

{
  "kind": "send_as",
  "external_account_id": 42,
  "email": "sales@example.com",
  "name": "Example Sales",
  "reply_to": "sales@example.com",
  "smtp_mode": "domain"
}

email は、このメールボックスのプライマリアドレスまたは送信が有効なアクティブなエイリアスとして、すでに登録されている必要があります。そのドメインは有効で、同じアカウントが所有している必要があります。smtp_mode: domain はダッシュボードで設定されたドメインルートに従います。smtp_mode: profile は ID を smtp_connection_id に固定します。プロファイルの直接選択は、アカウント所有者のメールボックスに限定されます。 メンバーであることだけでは、共有アドレス用の通常のsend_asを作成できません。

external_account_id は任意です。その意味を正確に理解することが重要です。

• 接続済みの Gmail、Outlook、または IMAP 受信トレイを介してそのアドレスのメールを読む場合は、指定します。ID はその受信トレイに紐づけられ、その受信トレイとの組み合わせでのみ使用できます。
• 代わりにメールが TrekMail メールボックスへ転送される場合は、省略します。

個人用の接続済み受信トレイを共有メールボックスに関連付けることはできません。接続した本人だけが使用できます。この場合は external_account_id を省略します。

MCP：create_identity を kind=send_as で呼び出します。ホステッド MCP では、上記のとおり親の mailbox_id を指定します。

4. 送信、下書き、予約、返信、転送

通常のメッセージ操作は、同じソースの組み合わせを受け取ります。

{
  "external_account_id": 42,
  "identity_id": 91,
  "to": ["customer@example.net"],
  "subject": "Hello",
  "body": { "text": "Hello from Example Sales" }
}

identity_id は、即時送信、下書きの保存/更新、予約送信でサポートされます。返信/転送の準備では external_account_id を受け取り、配信ヘッダーから一致する ID を選択します。キュー内のメッセージが実際に実行される際、選択された ID は再認証されます。そのエイリアス、ドメイン、プロファイル、または接続済みアカウントを無効にすると、別の差出人アドレスに暗黙的に切り替わるのではなく、配信が停止します。

MCP ツール：send_message、save_draft、update_draft、schedule_message、prepare_reply、prepare_reply_all、prepare_forward。

共有メールボックスとして送信する

Message APIやMCPから共有受信箱で送信するには、メンバーに読み取りとこのアドレスで送信の両方が必要です。メンバーのトークンとshared_mailbox_idを使います。共有メールボックスのトークンは読み取り専用です。

{
  "shared_mailbox_id": 5,
  "to": ["customer@example.net"],
  "subject": "Re: your order",
  "body": { "text": "Answered by the team" }
}

トークンはメンバーに紐づいたままで、監査記録も同様です。 GET /messages/identities?shared_mailbox_id=5 でそのメールボックスが送信できるアドレスを一覧できます。

想定される 2 つの拒否:

• shared_mailbox_not_a_sender (403): トークン自体が共有メールボックスに紐づいています。読み取りには影響せず、送信のみメンバーを必要とします。
• shared_mailbox_send_denied（403）：メンバーには読み取りとこのアドレスで送信の両方が必要です。

個人のウェブメールにあるチームのアドレスは、Message APIの差出人アドレスとして一覧に表示されず、指定もできません。identity_idが拒否されると422 identity_unavailable、チームのアドレスを変更または削除すると422 identity_delegatedが返ります。これらの応答にはhintとidentity_idが含まれ、取得できる場合はshared_mailbox_idとmember_idも含まれます。共有メールボックスからの送信が拒否されるとshared_mailbox_idが含まれ、送信のみの権限を持つメンバーにはmember_idも返ります。再試行する前にヒントを確認してください。共有メールボックスや差出人の指定を省くと、別のアドレスから送信されます。

Message APIでは読み取りとこのアドレスで送信を持つメンバーがshared_mailbox_idで予約送信できます。Webメールは共有受信箱内で予約送信を提供しません。一覧、時間変更、キャンセルには同じshared_mailbox_idを渡します。行は共有メールボックスに属し、予約した人の情報は行自体にはありません。

MCP: send_message、schedule_message、list_identities が shared_mailbox_id を受け付けます。ホスト型 MCP では mailbox_id はメンバーのままです。

返信ポリシー

PATCH /api/v1/messages/identities/reply-policy
Authorization: Bearer tm_msg_...
Idempotency-Key: reply-policy-v1

{ "reply_from_policy": "recipient" }

recipient は、可能であればメッセージを受信したアドレスから返信します。通常のメールボックスメールでは、default は常にメールボックスのデフォルトから開始します。MCP は set_reply_from_policy を使用します。

安全性と分離のルール

• SMTP 認証情報がメッセージ API または MCP の応答に含まれることはありません。
• すべての外部アカウントと ID は、メッセージトークンのメールボックスに限定されます。
• 接続済みの差出人 ID は、対応する正確な external_account_id との組み合わせでのみ使用できます。メールボックス所有の ID は、この値を指定しない場合にのみ使用できます。
• 差出人アドレスは、メールボックスアドレスまたは送信が有効なエイリアスとして、すでに許可されている必要があります。API で任意の差出人アドレスを作ることはできません。
• 作成前に有効なルートが必要であり、配信時に再度確認されます。
• カスタム Reply-To ヘッダーは、ID に保存された Reply-To と競合できません。
• MCP による ID とプロファイルの変更には、適切な書き込み権限が必要です。ローカルでホストする MCP の管理者は書き込み操作に明示的な承認を要求できます。送信にもメッセージごとの確認が必要です。

新しいトークンスコープ文字列は必要ありません。既存の smtp:* と messages:* のトークンは、現在の権限に従って引き続き動作します。

適用される送信制限

API 呼び出しにも独自の不正使用対策が適用されます。デフォルトでは、メッセージトークンごとに 1 分あたり 60 件の送信リクエスト、メールボックス全体で 1 日あたり 100 件の API 送信です。最終的にどのサーバーがメールを配信するかにかかわらず適用されます。