API と MCP によるメールクライアント設定

TrekMail は、ダッシュボードの アプリとデバイスで使用されるものと同じ接続データを REST と MCP で提供します。どちらのインターフェースも読み取り専用で、メールボックスの読み取りアクセスが必要です。

メールボックスのパスワード、アプリパスワード、カスタム SMTP プロバイダーの認証情報は返されません。ユーザーはメールアプリにアプリパスワードを直接入力します。メールボックスで引き続き許可されている場合はメールボックスのパスワードも使えます。ドメインがカスタムプロバイダー経由で送信する場合も、外部アプリは TrekMail の公開 SMTP endpoint に送信し、その背後で TrekMail がドメインの非公開ルートを適用します。

接続設定を取得する

GET /api/v1/mailboxes/{mailbox_id}/client-setup?lang=en
Authorization: Bearer tm_live_...

必要な内部スコープは mailboxes:read です。トークンの任意の domain_ids と mailbox_ids 制約も適用されます。

レスポンスには次が含まれます。

• 受信 IMAP ホスト、SSL ポート、ユーザー名、準備状況
• 送信 SMTP ホスト、SSL ポート、ユーザー名、準備状況
• カレンダーと連絡先用 DAV サーバー URL、接続準備状況、返されたアドレスがブランド化されているか
• アプリとデバイスに表示される Gmail、Outlook、Apple Mail、Thunderbird、汎用 IMAP のローカライズ済み 3 ステップガイド
• sending.mode: platform、profile、または not_configured
• sending.reason: 送信メールが準備できていない場合の、安定した機械可読の理由
• apple_mail_profile.available: 受信と送信の両方が準備済みの場合だけ true
• shared_mailboxes.native_access_enabled、namespace、items[]。
• authentication.client_auth_mode: app_password_onlyまたはpassword_or_app_password。
• authentication.accepted_passwords: それぞれ["app_password"]または["mailbox_password", "app_password"]。
• authentication.app_passwords_endpoint: メールボックスのアプリパスワード管理エンドポイント。
• 明示的な安全保証としての password_included: false

shared_mailboxes.items[]にはネイティブのフォルダーアクセスが有効な場合、読み取り権限を持つメンバーだけが含まれます。delegated_send_addressesは利用可能なチームの差出人アドレスの別リストで、各項目にid、email、display_nameがあり、空の場合もあります。フォルダーへのアクセス権は付与せず、送信準備の確認でもありません。これらのアドレスはMessage APIのIDではありません。White Labelでも、プラットフォームのホスト名をコピーせず、返されたサーバーを使ってください。

委任された各項目には、永続的な native_access_status/native_access_ready、folders 内の正確な標準パス、サーバーが強制する operations、有効な send_as_ready/send_as_reason が含まれます。can_send は管理者が割り当てたこのアドレスで送信権限を示し、SMTP が利用できなくても true の場合があるため、自動化では両方の準備状況フィールドを確認します。メンバーメールボックスが無効、サインイン停止中、または直接ログイン無効でも共有メールボックスは表示されますが、送信者としての理由に mailbox_unavailable、mailbox_login_suspended、または direct_login_unavailable が返されます。従来の folder は正確な受信トレイパスを維持します。設定を案内する前に native_access_ready=true を待ってください。

SMTP は返信や転送を運びますが、送信済みコピーを保存しません。そのため sent_copy.smtp_saves_copy は false です。チーム全員が確認できるよう、コピーを sent_copy.folder（folders.sent と同じ値）に追加するようクライアントを設定します。クライアントがアーカイブや迷惑メールを自動対応付けしない場合、folders.archive と folders.junk が正確な移動先です。迷惑メールへの移動だけでサーバー側分類器の学習が保証されるわけではありません。

この endpoint は常に通常メンバーメールボックス IDでリクエストし、そのメンバー自身のアドレスとアプリパスワード、または許可されている場合はメールボックスのパスワードでメールクライアントを認証します。2 つ目のアカウントを作成したり、共有アドレスで直接認証したりしないでください。

shared_mailboxesのフォルダー一覧は、共有受信箱を読める人のネイティブアクセスを示します。itemsが空ならネイティブアクセスと読み取りを確認します。空の一覧は、共有アドレスへの全権限が取り消されたことを意味しません。パスワードは返されません。

任意の lang パラメーターは Apple プロファイル endpoint と同じ 13 言語を受け付けます。省略時は Accept-Language、次に既定ロケールが使用されます。各ガイドには安定した id、ローカライズ済みの 3 つの steps、および action（use_server_settings または download_apple_profile）があります。

connection_status=receiving_only は完全な設定成功ではありません。両方のサーバーを検証するクライアントへの接続を案内する前に、ドメインの送信ルートを設定または復旧してください。

connection_status=unavailable は、メールボックスのライフサイクルが変わり、直接認証できないことを示します。返されたサーバー情報を使用したり Apple Mail プロファイルを提供したりせず、メールボックスの状態を更新してください。

Apple Mail プロファイルをダウンロードする

GET /api/v1/mailboxes/{mailbox_id}/apple-mail-profile?lang=en
Authorization: Bearer tm_live_...
Accept: application/x-apple-aspen-config

レスポンスは .mobileconfig 添付ファイルです。対応する lang は en、es、fr、de、pt、it、nl、ru、zh、ja、ko、ar、he です。lang の省略時は Accept-Language、次に既定ロケールが使用されます。

プロファイルには IMAP と SMTP の設定が含まれますが、パスワードフィールドはありません。Apple がインストール中にパスワードを求めます。app_password_onlyではアプリパスワードを使い、password_or_app_passwordでは許可されているどちらのパスワードも使えます。送信メールが利用できない間、TrekMail は誤解を招くプロファイルを生成せず 409 mail_client_setup_not_ready を返します。

ウェブメールの設定、アプリパスワード、またはダッシュボードのメールボックス、 対象のメールボックス、セキュリティ、アプリパスワードで作成します。読み取り専用の設定エンドポイントでは作成できません。これらのパスワードとサインインモードを管理するRESTエンドポイントとMCPツールについては、APIとMCPによるメールアプリのパスワード管理を参照してください。

MCP ツール

ツールは同じ REST endpoints と認可規則を使用します。

MCP トランスポートはブラウザダウンロードではなく構造化されたツールコンテンツを返します。content_base64 をバイトとしてデコードし、file_name で保存します。デコード前に JSON や UTF-8 として解釈しないでください。

どちらもホスト型 OAuth スコープ mail:read が必要で、内部スコープ mailboxes:read に展開されます。これらは読み取り専用で、セルフホスト stdio サーバーの破壊的操作用環境フラグには依存しません。

エラー

設定 endpoint は次の sending.reason 値を返す場合があります: mailbox_unavailable、direct_login_unavailable、domain_unavailable、domain_deprovisioning、account_suspended、email_verification_required、mailbox_sending_disabled、smtp_not_configured、managed_smtp_not_in_plan、managed_smtp_entitlement_inactive、smtp_profile_unavailable、smtp_route_invalid。