White Label 브랜딩 API 및 MCP 가이드

도메인별 White Label 브랜딩은 대시보드 없이 API와 MCP를 통해 처음부터 끝까지 설정할 수 있습니다. 에이전트는 도메인의 브랜드 이름과 색상을 설정하고, 로고를 업로드하고, 브랜드 대시보드 및 웹메일 호스트를 켜고, 생성해야 할 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과 동일한 브랜딩 페이로드를 반환하므로 한 번의 요청으로 새 상태를 확인할 수 있습니다.

브랜딩 페이로드

{
  "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는 저장된 의도이며, 두 상태 필드를 사용해 대기, 활성, 실패 및 정리 상태를 구분할 수 있습니다. 호스트 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 인증서와 제한된 웹 경로가 준비될 때까지 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 본문에서 scope를 받고, DELETE는 쿼리 매개변수로 받습니다. 상속된 프로필에 대한 암시적 도메인 범위 변경은 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는 DNS가 활성화되기 전에 브랜드 환경을 확인할 수 있는 72 시간 URL을 생성합니다.

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 도메인이 필요합니다. 설정한 보낸 사람 주소는 계정에 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 관리자가 쓰기 작업을 보호하도록 선택했다면 쓰기를 활성화하세요.