White LabelブランディングAPI・MCPガイド

ドメインごとのWhite Labelブランディングは、ダッシュボードを使わずにAPIとMCPから一貫して設定できます。エージェントは、ドメインのブランド名と色の設定、ロゴのアップロード、ブランド化されたダッシュボードとWebメールホストの有効化、作成すべきDNSレコードの取得、DNS検証の要求を行えます。これはダッシュボードのBrandingタブが保存するものと同じブランディングです。APIを使うと、エージェントやスクリプトにこの作業を任せられます。

ブランディングはドメインごとに設定されます（ドメインは数値idです）。ドメインは独自のブランド（custom）を持つ、アカウントのデフォルトを継承する（inherit）、またはオフにできます。APIは、そのドメインのブランド化されたホスト名とCNAMEレコードを返します。返されたレコードは必ず正確にコピーしてください。このガイドの例からホスト名やCNAMEターゲットを組み立てないでください。

アドオンの利用権限

すべてのメールプランには、30 日間のWhite Labelトライアルとプレビューが含まれます。この期間を使ってブランドを設定し、ブランド化されたホストを顧客に公開する前に動作を確認してください。

APIにはWhite Labelダッシュボードと同じ利用権限が適用されます。

• 有効なトライアルまたは有料アドオン: 読み取りと書き込みのスコープを利用できます。有効にしたホストは、CNAMEが解決されSSL証明書が発行されると、pending_dnsからactiveに移行します。
• 解約後の猶予期間: アカウント所有者は、表示されたhard_delete_at時刻まで読み取り専用アクセスを維持します。書き込みはブロックされ、委任された接続はWhite Labelへのアクセスを直ちに失います。
• 有効な利用権限なし: White Labelスコープは認証情報の実効権限から削除され、MCPツールも読み込まれません。

保存済みトークンが以前White Labelスコープを持っていても、利用権限が無効になっている場合、APIは具体的な次の手順とともに403 scope_blocked_by_entitlementを返します。より広い権限のトークンを作成しても利用権限を回避できません。

必要なスコープ

ブランディングには専用のスコープがあります。これにより、通常のドメインを管理する自動化が、誤ってリセラーのIDを表示または変更することを防げます。

RESTエンドポイント

すべてのエンドポイントはhttps://trekmail.net/api/v1の下にあります。{id}は数値のドメインidです。

verify-dnsとpreviewを除くすべてのエンドポイントは、GETと同じブランディングペイロードを返すため、1回のリクエストで新しい状態を確認できます。

ブランディングペイロード

{
  "data": {
    "mode": "custom",
    "white_label_addon_active": true,
    "brand": {
      "id": 42,
      "name": "Northwind Mail",
      "primary_color": "#2563eb",
      "accent_color": "#10b981",
      "logo_url": "https://trekmail.net/storage/branding/42/light.png",
      "logo_dark_url": "https://trekmail.net/storage/branding/42/dark.png",
      "favicon_url": "https://trekmail.net/storage/branding/42/favicon.png",
      "support_email": "support@northwind.com",
      "support_url": "https://help.northwind.com",
      "sender_email": "noreply@northwind.com"
    },
    "mail_zone": {
      "enabled": true,
      "domain": "northwind.com",
      "dns_status": "pending_dns",
      "client_hosts_status": "pending_dns",
      "records": [
        { "type": "TXT", "name": "spf.northwind.com", "value": "v=spf1 include:spf.trekmail.net -all" },
        { "type": "CNAME", "name": "imap.northwind.com", "value": "imap.trekmail.net" },
        { "type": "CNAME", "name": "dav.northwind.com", "value": "trekmail.net" }
      ],
      "dav_url": "https://trekmail.net/dav/files/account/",
      "dav_ready": false,
      "cert_expires_at": null,
      "checked_at": "2026-08-29T06:20:11+00:00"
    },
    "hosts": [
      { "kind": "dashboard", "hostname": "dashboard.northwind.com", "subdomain_label": "dashboard", "enabled": true, "status": "pending_dns" },
      { "kind": "webmail", "hostname": "mail.northwind.com", "subdomain_label": "mail", "enabled": true, "status": "pending_dns" }
    ],
    "dns_records": [
      { "type": "CNAME", "name": "<returned dashboard host>", "value": "<returned CNAME target>", "proxied": false },
      { "type": "CNAME", "name": "<returned webmail host>", "value": "<returned CNAME target>", "proxied": false }
    ],
    "cname_target": "<returned CNAME target>"
  }
}

modeがoffの場合、brandとmail_zoneはnullです。mail_zone.enabledは保存された意図です。2つの状態フィールドを使って、保留中、アクティブ、失敗、クリーンアップの各状態を区別してください。ホストのstatusは、DNSとSSLがまだ保留中か、ホストがアクティブかを示します。例のプレースホルダー値は意図的なものです。公開する値は、返されたdns_recordsとcname_targetだけです。

mail_zoneはブランド独自のメールホスト名を表します（下記参照）。dns_statusはメールDNSの状態、client_hosts_statusはクライアントホストと証明書の状態を表し、どちらもoff、pending_dns、active、failedのいずれかです。recordsにはプロバイダーが公開する必要のあるDNSレコードが含まれます。dav_urlは常に安全に使用できます。ブランド化されたDAV証明書と制限付きWebルートの準備ができるまでTrekMail上に留まります。dav_readyがtrueになった場合のみ切り替えてください。その後、cert_expires_atにブランド化されたメールアプリホストの最も早い証明書有効期限が表示されます。

現在のブランディングを読み取る

curl -s "https://trekmail.net/api/v1/domains/123/branding" \
  -H "Authorization: Bearer tm_live_your_token"

ブランドを設定する（部分マージ）

PATCHは部分マージです。省略したフィールドはすべて保持されるため、変更する内容だけを送信してください。

curl -s -X PATCH "https://trekmail.net/api/v1/domains/123/branding" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-123-initial" \
  -d '{
    "mode": "custom",
    "name": "Northwind Mail",
    "primary_color": "#2563eb",
    "accent_color": "#10b981",
    "dashboard_enabled": true,
    "dashboard_label": "dashboard",
    "webmail_enabled": true,
    "webmail_label": "mail",
    "mail_zone_enabled": true,
    "support_email": "support@northwind.com",
    "support_url": "https://help.northwind.com",
    "sender_email": "noreply@northwind.com"
  }'

リクエスト本文のフィールドは次のとおりです。

ロゴをアップロードする

ロゴはbase64で送信します。slotはlight、dark、faviconのいずれかです。すべてのスロットでPNGとJPGを利用でき、faviconではICOも利用できます。最大1 MBです。セキュリティ上の理由からSVGは拒否されます。デフォルトのscope=domainはcustomモードのドメインだけを変更し、継承されたプロファイルには追従しません。inheritドメインから共有プロファイルを意図的に変更するには、scope=account_defaultを指定し、制約のないbranding:writeトークンを使用してください。ドメイン制約付きトークンではアカウントのデフォルトを変更できません。

curl -s -X PUT "https://trekmail.net/api/v1/domains/123/branding/logo/light" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-123-logo-light" \
  -d "{\"content_base64\":\"$(base64 -w0 logo-light.png)\"}"

DELETEでスロットを削除します。

curl -s -X DELETE "https://trekmail.net/api/v1/domains/123/branding/logo/dark" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-logo-dark-remove"

どちらも、更新されたlogo_url / logo_dark_url / favicon_urlを含むブランディングペイロードを返します。PUTではJSON本文、DELETEではクエリパラメーターでscopeを指定できます。継承プロファイルに暗黙的なドメインスコープの変更を行うと、422 inherited_brandが返されます。

DNSを検証する

CNAMEレコードを作成したら（下記のフローを参照）、検証をキューに入れます。

curl -s -X POST "https://trekmail.net/api/v1/domains/123/branding/verify-dns" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-verify"

{ "data": { "status": "queued", "hosts": 2 } }

これはバックグラウンドで実行されます。GET /brandingを再度読み取り、ホストのstatusがactiveに変わるのを確認してください。White Labelが失効している場合、リクエストは再有効化のヒントとともに403 scope_blocked_by_entitlementを返します。

ブランドのメールゾーンがある場合は同時に再確認されるため、mail_zone.dns_statusとmail_zone.client_hosts_statusも同じ呼び出しで更新されます。ゾーンのためにこの呼び出しを実行する必要はありません。待機中のゾーンは定期的に再確認され、レコードが解決してから数分以内に有効になります。verify-dnsは次回の定期確認を待たず、今すぐ確認するよう要求するだけです。

ブランド独自ドメインでのメール

mail_zone_enabledを使うと、顧客のメールアプリとDAV同期クライアントにリセラーの名前を表示できます。有効にしてから、mail_zone.recordsで返されたすべてのレコードを公開してください。SPF TXTレコードに加え、IMAPとDAVのCNAMEレコードが含まれます。レスポンスに含まれる正確な名前とターゲットが正式な値です。

返されたレコードがCNAMEを要求している場合はAレコードではなくCNAMEを使い、Cloudflareのクラウドをグレーのままにしてください。メールとDAVクライアントは直接接続する必要があります。DNSプロキシは証明書の検証やブラウザ以外のプロトコルを妨げることがあります。レスポンスには公開すべきすべてのレコードが示されるため、推測したメールレコードを追加しないでください。

レコードが解決されると、TrekMailは証明書を発行してホスト名を有効にします。mail_zone.client_hosts_statusがactiveに、mail_zone.dav_readyがtrueになるまで確認してください。返されたdav_urlを引き続き使用してください。DAVを安全に提供できるようになった後でのみ、プラットフォームのアドレスからブランド化されたアドレスに変わります。ホストの状態がfailedの場合はDNS検証を再度実行し、失敗が続く場合はサポートチケットを開いてください。

ライブプレビューを作成する

POST /branding/previewは 72 時間有効なURLを作成し、DNSが有効になる前にブランド化された画面を確認できます。

curl -s -X POST "https://trekmail.net/api/v1/domains/123/branding/preview" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-preview"

レスポンスには 72 時間後に期限切れとなるプレビューURLが含まれます。ブランディングがオフまたは未設定でプレビューするブランドがない場合は、422 no_brandが返されます。

ブランディングを削除する

curl -s -X DELETE "https://trekmail.net/api/v1/domains/123/branding?scope=domain" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-remove"

scope=domainはこのドメインだけを消去し、scope=allはアカウント全体のブランディングを消去します。ブランディングペイロードを返します。

MCPツール

20個のツールを含むwhite_labelツールセットのうち、7個がブランディングに対応します。接続に実効的なブランディングスコープがあり、White Labelが利用可能な場合にのみ登録されます。読み取りツールにはbranding:read、その他の6個にはbranding:writeが必要です。ローカルでホストされるMCPサーバーでは、管理者が書き込み操作を許可する必要がある場合もあります。

get_domain_brandingは読み取り専用です。所有者による解約後の猶予期間中は引き続き利用できますが、6個の書き込みツールはすべて表示されなくなります。White Labelの利用権限がなければ、これらのツールはtools/listに一切表示されません。

自律的なエンドツーエンドフロー

ドメインのDNSがCloudflareにある場合、エージェントは人の操作なしで、ブランディングのないドメインを稼働中のブランド化ホストにできます。既存のCloudflare DNSツール（apply_cloudflare_dns）で、get_domain_brandingが返すCNAMEを書き込めるためです。

1. ブランドを設定します。 set_domain_branding(mode=custom, name, primary_color, accent_color, dashboard_enabled=true, webmail_enabled=true)。
2. ロゴをアップロードします（任意）。set_domain_brand_logo(slot="light", content_base64=…)を実行し、darkとfaviconについて繰り返します。
3. DNSレコードを読み取ります。 get_domain_branding → 返されたdns_records配列をコピーします。値を推測したり生成したりしないでください。
4. CNAMEを書き込みます。 プロキシをオフにしてレコードを公開します。Cloudflareではグレーのクラウドに設定し、DNSとSSLの検証が動作するようにします。
5. 検証します。 verify_domain_branding_dns。
6. ポーリングします。 各ホストのstatusがactiveになるまでget_domain_brandingを再度呼び出します。
7. プレビューします（任意）。顧客をブランド化ドメインに誘導する前に、create_branding_previewでライブデモURLを作成します。

実行例（MCP）

set_domain_branding(
  domain_id=123,
  mode="custom",
  name="Northwind Mail",
  primary_color="#2563eb",
  accent_color="#10b981",
  dashboard_enabled=true,
  webmail_enabled=true,
  support_email="support@northwind.com",
  sender_email="noreply@northwind.com"
)

set_domain_brand_logo(domain_id=123, slot="light", content_base64="iVBORw0KGgo…")
set_domain_brand_logo(domain_id=123, slot="dark", content_base64="iVBORw0KGgo…")

get_domain_branding(domain_id=123)
# → Copy the returned dns_records exactly. Do not substitute an example host or target.

apply_cloudflare_dns(domain_ids=[123])   # writes the CNAMEs, proxy off

verify_domain_branding_dns(domain_id=123)

# poll until active
get_domain_branding(domain_id=123)
# → hosts[].status: "active"

create_branding_preview(domain_id=123)   # optional live demo

エージェントにブランド化されたホスト名と最終的なホスト状態を報告させ、単にpending_dnsのままではなく、実際に稼働したことを確認してください。

注意点

• 利用権限によってAPIとMCPの利用可否が決まります。 書き込みには有効なトライアルまたは有料アドオンが必要です。解約後、所有者には読み取り専用の復旧期間が与えられますが、他のユーザーはこれらのツールを直ちに失います。
• PATCHは部分マージです。 省略したフィールドは保持されます。アクセントカラーだけを変更するには{"accent_color":"#10b981"}を送信します。名前、ロゴ、切り替えを再送信する必要はありません。
• オフから再度有効にするにはmodeが必要です。 ブランディングが現在offの場合、modeを省略したPATCHでは有効になりません。mode=custom（またはinherit）を指定してください。
• sender_emailには検証済みDKIMドメインが必要です。 設定するFromアドレスは、アカウントですでにDKIMキーがプロビジョニングされているドメイン上にある必要があります。そうでなければ更新は拒否されます。カスタム送信者を設定する前に、ドメインのDKIM（retry_domain_dkim / get_dns_check）を検証してください。
• ロゴはbase64、≤1 MB、SVGは不可です。 PNGまたはJPG（faviconではICOも可）をcontent_base64として送信します。SVGは拒否されます。大きなソースファイルは先に圧縮してください。
• 返されたCNAMEレコードをプロキシしないでください。 Cloudflareのオレンジ色のクラウドや別のCDNプロキシは、DNSとSSLの検証を妨げます。返されたとおりにdns_recordsを公開し、proxied:falseに設定してください。
• 書き込み操作には適切なアクセス権が必要です。 get_domain_branding以外のすべてのツールはデータを変更します。必要な書き込みスコープを使用し、ローカルMCPの管理者が書き込みを保護している場合は書き込みを有効にしてください。