開発者向けTrekMail REST API概要

TrekMail APIを使用すると、HTTPクライアントやAIエージェントからドメイン、メールボックス、転送、DNS、メール移行、ウェブメール操作を管理できます。これにはメールの閲覧と送信、下書き、予約送信、フォルダー、連絡先、カレンダー、送信者情報、テンプレート、ブロック済み送信者が含まれます。認証済みリクエストにはBearerトークンを使用し、レスポンスはJSONで返され、APIアクティビティは監査されます。

利用できる機能

• JSON形式のリクエストとレスポンスを使用するREST API v1。
• Bearerトークン認証: 認証済みAPI呼び出しではCookieやセッションは使用しません。
• 必須の書き込み操作で使う冪等性キー。再試行時の処理重複を防ぎます。
• Retry-Afterヘッダーを伴うトークン単位のレート制限。
• ダッシュボードのAI Agents & API → Audit Logで確認できる監査ログ。
• 現在の接続における認証情報、トランスポート、安全性設定に応じてカタログが絞り込まれるMCPサーバー。したがって、範囲を限定したプロジェクト接続では、使用可能なツールだけが表示されます。
• ドメインエイリアス: セカンダリドメイン上の受信専用アドレスを、プライマリドメイン上の同じローカル部に接続できます。保存済みと稼働中の配信状態を区別し、安全に削除できます。APIとMCPによるドメインエイリアスを参照してください。
• デュアルトークンアーキテクチャ: インフラストラクチャ用のopsトークンと、メールの閲覧、送信、下書き、予約送信、連絡先、カレンダー、送信者情報、テンプレート、フォルダーなど、メール操作全般に使うmessageトークンを分離しています。
• 送信到達性とバウンスの分析: ダッシュボードから送信済み、配信済み、ハードバウンス、ソフトバウンスの集計に加え、受信者ごとのSMTPコードとレスポンスを取得できます。到達性とバウンスを参照してください。
• メールボックスのストレージ使用量: list_mailboxesとget_mailboxはused_mb、quota_mb、allocation_mb、is_pooledを返すため、エージェントはダッシュボードにアクセスせずに上限へ近づいているメールボックスを見つけられます。
• ホワイトラベル管理: APIまたはMCPから、セットアップの確認、ドメイン単位のブランド管理、クライアントの招待、ロールとドメインの制御、アクセスの停止または復元、アクティビティの確認を行えます。ブランド設定ガイドとチーム管理ガイドを参照してください。

Drive APIとファイル自動化

Driveは公開APIサーフェスの一部です。Account DriveとメールボックスのDriveスペース、使用量、フォルダーの参照、アップロード、ファイルとフォルダーの管理、ゴミ箱、一括操作、公開共有リンク、同期デバイスのパスワード管理、Drive Storageアドオン状態の読み取り専用確認に対応します。

Driveは十一個のopsトークンスコープ、drive:account:read、drive:account:write、drive:account:share、drive:account:purge、drive:mailbox:read、drive:mailbox:write、drive:mailbox:share、drive:mailbox:purge、drive:addon:read、drive:devices:read、drive:devices:writeを使用します。Driveアドオンの請求操作、購入、容量変更、キャンセルは引き続きダッシュボード専用であり、APIまたはMCPの書き込み操作としては公開されません。

Drive API概要またはDrive APIクイックスタートから始めてください。

デュアルトークンアーキテクチャ

APIは独立した二種類のトークンを使用します。用途に応じて一方または両方を使用できます。

Opsトークンとmessageトークンには、それぞれ個別のスコープとレート制限があります。MCPサーバー環境で設定すれば、単一のエージェントで両方のトークンを同時に使用できます。

MessageトークンはProおよびAgencyプランで利用できます。

始める前に

• すべてのプランでAPIにアクセスできます。
  • Nano: Email Verifier。Drive Storageアドオンを追加すると、Drive APIとMCPへのフルアクセスが可能です。
  • Starter: DriveとEmail Verifierの全機能、およびその他のインフラストラクチャ領域への読み取り専用アクセス。それらの書き込み操作にはダッシュボードを使用してください。
  • Pro / Agency: Messageトークンを含む基本APIへのフルアクセス。ホワイトラベルのトライアルまたは有料アドオンが有効な間は、ホワイトラベルのスコープも追加されます。
• AIエージェントを接続しますか? 対応クライアントでhttps://trekmail.net/mcpをリモートMCPサーバーとして追加してください。ブラウザ認証に対応していれば、手動トークンは不要です。リモート、CLI/デスクトップ、ブリッジ、セルフホストの各方法については、AIエージェントの接続（MCP）を参照してください。
• 独自の連携を作成しますか? AI Agents & API → Tokens → Create tokenでtm_live_トークンを作成し、Authorization: Bearer …として送信します。APIトークンの作成と管理を参照してください。
• APIを初めて使いますか? AI Agents & APIページ上部のStart tourをクリックすると、接続方法、トークン管理、接続済みアプリ、監査ログの短いガイドを確認できます。

認証の仕組み

すべてのリクエストでAuthorizationヘッダーにトークンを含める必要があります。

Authorization: Bearer tm_live_abc123...

Opsトークンはtm_live_、messageトークンはtm_msg_で始まります。どちらも作成時に一度だけ表示され、再表示はできません。

トークンがない、取り消されている、または期限切れの場合、APIは401を返し、エラーコードはunauthenticatedとなります。

ベースURLとバージョニング

すべてのエンドポイントは次のパスにあります。

https://trekmail.net/api/v1

ベースURLはAI Agents & APIダッシュボードのQuick Referenceに表示されます。バージョンはURLパスに含まれます。将来v2が導入された場合も、v1は引き続き動作します。

レスポンス形式

成功したレスポンスは、単一リソースまたはページ分割されたリストをdataキーに含むJSONを返します。

{
  "data": [
    { "id": 1, "domain": "example.com", "status": "active" }
  ],
  "links": { "next": "...", "prev": null },
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

エラーレスポンスは一貫した構造に従います。

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired API token",
    "hint": "Check that your token is correct and has not been revoked.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

リクエストID

すべてのレスポンスにX-Request-Idヘッダーが含まれます。リクエストでX-Request-Idを使って独自の値を渡すこともできます。その値はそのまま返され、監査証跡に記録されます。

レート制限

各トークンには分単位のレート制限があります。上限に達すると、APIは429を返し、Retry-Afterヘッダーで再試行できる時点を示します。

破壊的な操作（削除インテント）には、トークン単位の日次追加上限と、連続する削除間のクールダウンがあります。

移行の書き込み操作（開始、キャンセル、再試行）には、トークンごとに毎分10リクエストという専用のレート制限があります。さらにサーバー全体の同時実行上限があり、グローバルに実行中の移行が多すぎる場合は503を返します。

Messageトークンには別の制限が適用されます。既定値は、トークンごとに毎分読み取り30リクエスト、送信60リクエスト、日次で成功した読み取り5,000件、および単一のメールボックス全体で日次API送信100件です。第二の送信安全カウンターは、既定でトークンごとに日次500件です。通常は、より低いメールボックス上限が先に適用されます。これらのAPI保護策は、プランのマネージドSMTP制限や外部プロバイダー独自の制限に代わるものではありません。

冪等性

冪等と指定された状態変更エンドポイントには、Idempotency-Keyヘッダーが必要です。これは自動再試行によって処理が重複する可能性がある作成、更新、送信、削除に適用されます。プロバイダー検出や接続テストのような読み取りに近いPOST操作には不要です。エンドポイント表またはOpenAPI仕様を確認してください。同じ本文で同じキーを送信すると、APIは重複を作成せずに元のレスポンスを再現します。

Idempotency-Key: create-mailbox-alice-2024

同じキーを異なる本文で送信すると、APIは409 Conflictを返します。

メールボックスのストレージ割り当て

メールボックスまたは招待を作成するすべてのエンドポイント、POST /api/v1/mailboxes、/api/v1/mailboxes:bulk、/api/v1/mailboxes/invites、/api/v1/mailboxes/invites:bulkは、任意の整数storage_allocation_mbを受け付けます。

割り当ては、稼働中のプールから既存の専用メールボックスと保留中の専用招待を差し引いた容量に対して検証されます。一括エンドポイントでは、バッチ全体の割り当ての合計も検証し、過剰割り当てになる場合はバッチ全体を422 storage_pool_exceededで拒否します。専用メールボックスの削除時、招待の利用時（割り当ては新しいメールボックスへ移動）、保留中の招待の期限切れ時にプールは更新されます。

招待の場合、割り当てはアクセスコードに記録され、利用時に新しいメールボックスへコピーされます。利用時にプールが要求された割り当てを収容できなくなっている場合（たとえば、その間に別の管理者が専用割り当てを増やした場合）、利用を失敗させず、新しいメールボックスを共有へ安全にダウングレードし、受信者の成功ページに通知を表示します。

メールボックスのDriveアクセス

各メールボックスにはdrive_accessレベルがあり、利用者がウェブメール内でDriveのどこまでアクセスできるかを決定します。これはメールボックスリソースで返され、PATCH /api/v1/mailboxes/{id}、または多数のメールボックスを一度に変更する場合はPOST /api/v1/mailboxes:drive-accessで設定できます。

ストレージはアカウント全体でプールされるため、これは一人の利用者がファイルでプールをどの程度使用できるかを制御する設定です。

メールボックスのサインイン停止

メール受信を継続したまま、メールボックスのサインインを停止できます。ウェブメール、IMAP、SMTP、デバイスパスワードは拒否され、開いているセッションは終了しますが、配信には影響しません。そのためバウンスは発生せず、サインインを復元するとすべてのメールが待機しています。POST /api/v1/mailboxes/{id}:suspend-login（復元は:resume-login）、または多数のメールボックスではPOST /api/v1/mailboxes:login-accessで設定します。

メールボックスリソースではlogin_suspended、login_suspended_at、login_suspended_reasonとして報告されます。利用者がサインインできるかはlogin_suspendedを、メールボックス自体が稼働中かはstatusを確認してください。停止されたメールボックスもメールを受信し続けるため、activeのままです。:pauseは別の機能で、statusをdisabledに設定し、配信も停止します。

APIによるメールボックスのサインイン停止を参照してください。

一括エンドポイントはmailbox_ids、domain_id、allのうちセレクターをただ一つ受け取り、実行結果を返します。

{ "data": { "drive_access": "attachments_only", "matched": 24, "updated": 21, "skipped_shared": 3 } }

一つのドメインが一人の顧客に対応する場合は、domain_idセレクターを使用します。すでに要求されたレベルにあるメールボックスはmatchedには数えられますがupdatedには数えられないため、この呼び出しは安全に繰り返せます。

共有メールボックスは、単一エンドポイントでは422 drive_access_not_applicableで拒否され、一括エンドポイントではスキップされて件数に含まれます。共有メールボックスには固有のウェブメール利用者がおらず、メンバーが自身のレベルで開くため、共有行に値を保存しても何も変わりません。

この制限はインターフェイスだけでなくAPIにも適用されます。制限されたメールボックスのDriveスペースはGET /api/v1/drive/spacesに表示されず、そのファイルをIDで要求すると404が返り、そのメールボックス用の同期デバイスは作成できません。

転送アドレス

GET /api/v1/domains/{id}/forwarding-addressesは単なる一覧以上の情報を返します。転送アドレス自体からは分からない二つの情報があるためです。

{
  "data": [ { "id": 8, "address": "sales@acme.com", "local_part": "sales",
              "domain_id": 4, "recipients": ["team@example.net"], "is_active": true } ],
  "limits": { "used": 1, "max": 100, "recipients_per_address": 15 },
  "delivery": { "active": true, "requires_plan": "pro",
                "paused_until": null, "paused_reason": null }
}

• limits.maxはドメイン単位で、プランによって異なります。Proでは100、Agencyでは300、NanoまたはStarterでは保存済みだが非アクティブなルールが25です。
• delivery.activeは、これらのルールが現在メールを転送しているかどうかを示します。プランがfalseとなるのはrequires_plan未満の場合であり、falseとなるのはpaused_untilが設定されている間も同様です（アカウントが毎時の送信上限を超えています。プラン別送信上限を参照してください）。ルールがis_active: trueでも配信されない場合があるため、転送が機能していると報告する前に、deliveryを確認し、is_activeだけで判断しないでください。

配信できないプランでも作成は許可され、201が返されます。ルールは保存され、アップグレード後に動作を開始します。これは、そのようなルールを保存済みかつ非アクティブとして表示するダッシュボードと同じ動作です。

拒否時は422が返り、error.codeはvalidation_errorまたはlimit_exceededに設定されます。原因には、ドメイン上ですでに使用中のアドレス、ループを起こす同一ドメインの受信者、正常に機能するMXがない受信者ドメイン、ドメイン単位の上限到達があります。

これらのエンドポイントのPOSTとDELETEにはIdempotency-Keyが必要ですが、PATCHには不要です。

配信履歴

GET /api/v1/domains/{id}/forwarding-addresses/{addressId}/logは、最近のメールで実際に起きたことを新しい順に返します。

{
  "data": [
    { "id": 91, "occurred_at": "2026-07-27T09:12:04+00:00", "outcome": "delivered",
      "from": "rfq@northgatesupply.com", "to": "sales@example.net",
      "smtp_code": "2.0.0", "smtp_response": "250 2.0.0 OK" }
  ],
  "address": "sales@acme.com",
  "window": { "retention_days": 30, "max_events": 200 }
}

outcomeはdelivered、deferred（一時的な失敗で再試行中）、failed（受信者のサーバーが拒否）、blockedのいずれかです。最後の値は、転送の前に当社のspamフィルターがメッセージを停止したため、受信者には一切届かなかったことを意味します。blockedをバウンスとして扱うと、問題が当社側で発生したにもかかわらず、受信サーバー側を調査することになります。

パラメーターはlimit（1から200、既定値100）のみです。保存期間はプランに応じて決まり、Agencyでは30日、それ以外では7日です。転送イベントは削除されるため、それより古いデータは取得できません。

共有（チーム）メールボックス

共有メールボックスはsupport@やsales@のようなチーム受信トレイで、メンバーが自身の通常のメールボックスアカウントを通じて、ウェブメールで開き、ネイティブアクセスが有効な場合は委任されたIMAPフォルダーとしても開きます。共有パスワードや個別のログインはありません。アクセス権は単純です。すべてのメンバーが閲覧でき、単一のcan_sendフラグによって、そのメンバーがそのアドレスとして返信できるか（true）、読み取り専用か（false）を制御します。メンバーロールはありません。

GET /api/v1/mailboxesとGET /api/v1/mailboxes/{id}は、mailbox_type（"user"または"shared"）と真偽値is_sharedを返すようになりました。共有メールボックスにはshared_member_countも含まれます。メンバーエンドポイントを呼び出す前に、これらのフィールドを使ってチーム受信トレイと通常のメールボックスを区別してください。

メンバーエンドポイントでは、既存のmailboxes:read / mailboxes:writeスコープを再利用します。共有メールボックス専用のスコープはありません。

ネイティブメールアプリからのアクセスを確認するには、通常メンバーのメールボックスに対してGET /api/v1/mailboxes/{member_mailbox_id}/client-setupを呼び出します。そのshared_mailboxesオブジェクトは、永続的なネイティブ準備状態、実効的なSend As準備状態と理由、Inbox/Sent/Archive/Junkの正確なパス、許可される操作を報告します。can_sendは割り当てられたCan reply権限であり、SMTPが現在利用可能である証明ではありません。このエンドポイントがパスワードを返すことはありません。共有メールボックスのIDで呼び出すと、その共有アドレスは直接認証できないため422 direct_login_unavailableを返します。

メンバーの削除、can_sendの変更、共有メールボックスから通常への変換を行うと、ネイティブアクセスが有効な場合にメールサーバーの権限が同期されます。503 native_access_sync_failedレスポンスは再試行可能であり、操作が部分的に適用されることなく、メンバーシップ、権限、メールボックス種別が変更前のまま保持されたことを保証します。

利用可能なエンドポイント

Driveには独自のリファレンスがあるため、ここでは繰り返しません。Drive API概要を参照してください。後方互換性のために維持されているアカウントレベルのSMTPエンドポイントは、現行として一覧に載せず、ドメイン単位のSMTPルーティングで説明しています。

Cloudflareエンドポイントはダッシュボードと同じフローに従います。トークンを検証し、ゾーンを一覧表示し、ドメインを接続し、DNS変更をプレビューしてから適用します。/cloudflare/previewと/cloudflare/applyはどちらも、ドメイン単位の任意の制御を二つ受け付けます。

• included_recordsは、変更対象とするレコードの許可リストで、ドメインIDをキーとします: { "123": ["mx_primary", "spf_record"] }。省いたレコードはスキップされるため、MXとSPFだけを適用し、DKIMは後で処理できます。すべてのレコードを適用するには、このフィールドを省略します。
• confirmed_conflictsは、値の異なる既存レコードがプレビューで検出された場合に、そのレコードIDをここへ列挙し（同じ{ domain_id: [record_ids] }形式）、置き換えを許可します。

レコードID（mx_primary、spf_record、dkim_primary、dmarc_main、…）はプレビューレスポンスから直接得られます。そのため一般的なエージェントは、最初にプレビューを呼び出し、必要なIDをapplyへ渡します。

POST /api/v1/cloudflare/apply
{
  "domain_ids": [123],
  "included_records": { "123": ["mx_primary", "spf_record"] },
  "confirmed_conflicts": { "123": ["dmarc_main"] }
}

ドメイン単位のSMTPルーティングとアカウントのデフォルト

SMTPはドメイン単位で設定します。各ドメインは、マネージドプラットフォーム送信、保存済みSMTPプロファイル（独自プロバイダーで、複数ドメインに再利用可能）、または「未設定」という三つのルートから一つを選びます。また、アカウント全体の単一のデフォルトによって、新しいドメインが最初に使うルートが決まります。

ドメイン単位のエンドポイント（smtp:read / smtp:write）:

ルートの本文に関する注意事項:

• smtp_mode=platformはマネージド送信を選択します。smtp_mode=profileにはsmtp_connection_idが必要です。not_configuredはルートを消去します。
• smtp_mode=inheritを指定すると、ドメインはアカウントのデフォルトをリアルタイムで追従し、デフォルトが変更されるたびにこのドメインも変更されます。ウェブUIは常に具体的なルートを書き込みますが、バックエンドは引き続きinheritに対応しています。このためGETはeffective_smtp_modeを返し、inheritが現在どの値に解決されているかを示します。
• set_account_default: trueは、ダッシュボードのMake this the account default切り替えに相当するAPI設定です（新しいドメインはこのルートで開始）。apply_to_all: trueはApply to all domainsボタンに相当します（すべてのドメインを一度だけこのルートへ切り替えます）。

アカウント全体のデフォルトエンドポイント（smtp:read / smtp:write）:

アカウントのデフォルトだったプロファイルを削除すると、デフォルトはプランの基準値に戻ります。

レガシーエンドポイント。 アカウントレベルのGET/PUT /api/v1/smtp（およびDELETE /api/v1/smtp/{id}、POST /api/v1/smtp:test、GET /api/v1/smtp:test-status/{jobId}）は後方互換性のため残されていますが、ドメイン単位のルーティングは制御しなくなりました。上記のドメイン単位エンドポイントと/smtp/defaultエンドポイントを使用してください。レガシーMCPツールのget_smtp_config / update_smtp_configも同じ理由で非推奨です。

ホワイトラベルのブランド、クライアント、チームアクセス

ブランドはbranding:read / branding:writeを使用してドメイン単位で設定します。ドメインは独自ブランド（mode=custom）を使用するか、アカウントのデフォルトを継承する（mode=inherit）か、無効にします。有効なホワイトラベルのトライアルまたは有料アドオンが必要です。キャンセル後も、表示された猶予期間中は所有者が読み取り専用の復旧アクセスを保持します。ドメインのdns_recordsを読み取り、返されたレコードをそのまま公開してください。例からホスト名やCNAMEターゲットを推測しないでください。

PATCHは部分マージであるため、省略したフィールドは保持されます。ブランドが現在無効な場合は、再び有効にするためmodeを渡してください。カスタムsender_emailはDKIMキーが検証済みのドメインに属している必要があります。mail_zone_enabledはブランド独自のドメインでメールアプリとDAV同期を提供します。これは単一ドメインではなくブランドに属するため、mode=customまたはscope=account_defaultが必要です。inheritドメインは422 inherited_brandを返します。プロビジョニングを追跡し、準備済みのDAVアドレスだけを使用するには、mail_zone.dns_status、mail_zone.client_hosts_status、mail_zone.records、mail_zone.dav_url、mail_zone.dav_readyを読み取ってください。エージェントの完全なワークフローについては、ホワイトラベルのブランド設定APIとMCPガイドを参照してください。

アカウントレベルのホワイトラベルサーフェスでは、/api/v1/white-labelの下に13個のルートが追加されます。これには状態とセットアップの進行状況、現在有効なアクセスカタログ、メンバー一覧とライフサイクル操作、アカウントアクティビティ、メンバーごとの操作履歴とサインイン履歴が含まれます。members:read、members:write、activity:readを使用します。アクセス権は常に、アカウントの資格、その人物の現在のメンバーシップ、認証情報への付与、ドメイン制約の共通部分です。ルート表と状態遷移については、APIとMCPによるホワイトラベルチームの管理を参照してください。

OpenAPI仕様は、Postman、Insomnia、コードジェネレーターへインポートできる/api/openapi.jsonとして公開されています。

クイック修正

• 401 "unauthenticated": Authorization: Bearer <token>ヘッダーがあり、トークンが取り消されておらず期限切れでもないことを確認してください。
• 403 "plan_api_disabled": 要求したスコープは現在のプランに含まれていません。NanoはEmail Verifier（Drive Storageアドオンを購入済みならDriveも）を利用できます。その他のAPIにはStarter以上へアップグレードしてください。
• 403 "token_scope_blocked_by_plan": トークンに、現在のプランでは利用できないスコープが含まれています。そのトークンを取り消し、許可されたスコープで新しいトークンを作成してください。
• 403 "scope_blocked_by_entitlement": アドオンが無効であるか、猶予期間中の書き込み操作であるため、保存済みのホワイトラベル付与を利用できません。ホワイトラベルを再有効化してから、認証情報を再発行または再認証してください。
• 403 "scope_blocked_by_membership": 現在のメンバーロールは、要求した操作よりも権限が限定されています。所有者に変更を依頼してください。再認証だけではメンバーシップを拡張できません。
• 422 "missing_idempotency_key": エンドポイントリファレンスで指定された書き込み操作にIdempotency-Keyヘッダーを追加してください。
• 403 "mailbox_sending_paused": そのメールボックスからの送信メールが所有者本人によるものに見えなくなったため、送信が停止されています。通常はパスワードが第三者に渡ったことが原因です。閲覧、一覧表示、その他すべてのエンドポイントは引き続き動作します。拒否されるのは送信だけであり、再試行しても解除されません。メールボックスのパスワードを変更する必要があり、その後サポートが送信を再開します。メールを送信できない理由を参照してください。
• 429 レート制限: 再試行する前に、Retry-Afterヘッダーで指定された時間だけ待ってください。

メール送信: 本文、ヘッダー、到達性

POST /api/v1/messages/sendは、{to, subject, body: {text, html}, attachments, reply_to_message_id, headers}形式のリクエストを受け取ります。

• body.textとbody.htmlはいずれも任意ですが、少なくとも一方が必要です。body.textだけを指定した場合は、<p>段落を使用したHTML代替を自動生成します（空行は段落を分割し、単一の改行は<br>になります）。これにより、あらゆる最新クライアントで通常のメールとして表示されます。等幅表示が必要な場合は、リテラルの<pre>...</pre>をbody.htmlで送信してください。
• headersは、ユーザーが指定する任意の送信ヘッダーオブジェクトです。許可リストはList-Unsubscribe、List-Unsubscribe-Post、Reply-To、および任意のX-*カスタム追跡ヘッダーです。その他の名前（From、Subject、Message-Id、Authentication-Resultsなど）はプラットフォームが管理するため、422で拒否されます。CR/LFを含む値も拒否されます（ヘッダーインジェクション対策）。値はRFC 2822に従って998文字までに制限されます。
• 一括送信や自動化のユースケースについては、一括送信者向け到達性ヘッダーのセクションでList-Unsubscribeの設定とアカウント全体のauto_list_unsubscribe切り替えを参照してください。