API와 MCP로 화이트 라벨 팀 관리하기

대시보드로 다시 전환하지 않고도 화이트 라벨 계정을 관리할 수 있습니다. REST API와 MCP 서버는 계정 설정 상태, 고객과 팀 구성원, 역할, 도메인 접근 권한, 초대, 일시 중지, 제거, 복원, 활동 기록을 지원합니다. 브랜딩은 동일한 화이트 라벨 도구 모음과 별도의 브랜딩 안내서에서 다룹니다.

중요한 경계는 간단합니다. 연결은 그 배후 사용자가 이미 가진 권한보다 더 많은 접근 권한을 부여할 수 없습니다. 특정 도메인으로 제한된 관리자는 관련 없는 도메인에 사용자를 초대할 수 없고, 사용자 지정 역할은 호출자에게 없는 권한을 부여할 수 없습니다.

사용 가능한 기능

전체 MCP 카탈로그에는 현재 stdio를 통한 261개 도구와 호스팅 HTTP를 통한 최대 260개 도구가 포함됩니다. 화이트 라벨은 20개 도구를 제공합니다. 브랜딩용은 일곱 개이고, 계정, 구성원, 활동 관리용은 13개입니다.

이 도구들은 모든 사용자에게 로드되지 않습니다. TrekMail은 tools/list를 구성하기 전에 계정의 현재 화이트 라벨 사용 권한, 사용자의 현재 구성원 자격, 토큰 또는 OAuth 권한 부여, 도메인 제한, 선택한 도구 모음, 로컬 안전 설정을 평가합니다. 화이트 라벨 접근 권한이 없는 연결에는 스키마 자체가 제공되지 않습니다.

사용 권한 상태

화이트 라벨 읽기 권한이 있으면 GET /api/v1/white-label 또는 get_white_label 도구를 호출하여 active와 읽기 전용 grace를 구분하고 설정 진행 상황과 유예 기한을 확인할 수 있습니다. 사용할 수 없는 계정은 해당 엔드포인트를 호출할 수 없습니다. 저장된 자격 증명에 계정이 더 이상 사용할 수 없는 화이트 라벨 범위가 남아 있으면 API는 scope_blocked_by_entitlement를 반환하고 다시 활성화할 위치를 설명합니다.

범위

구성원 활동 엔드포인트에는 activity:read와 members:read가 모두 필요합니다. 응답에 활동뿐 아니라 구성원 레코드도 포함되기 때문입니다. 호스팅 OAuth 연결은 tools:white_label 선택기를 사용하여 이 도구 제품군을 요청합니다. 유효한 REST 범위는 여전히 계정과 구성원 자격에 따라 제한됩니다.

자체 호스팅 MCP 서버에서 도구 모음 허용 목록을 사용한다면 TREKMAIL_TOOLSETS에 white_label을 추가하세요. 쓰기 도구에는 아래에서 설명하는 로컬 안전 게이트도 적용됩니다.

REST 엔드포인트

모든 경로는 https://trekmail.net/api/v1 아래에 있습니다.

이 표의 모든 쓰기 작업에는 Idempotency-Key 헤더가 필요합니다. 같은 키로 같은 요청을 반복하면 원래의 안전한 결과가 반환됩니다. 초대 토큰처럼 재실행에 포함된 일회성 비밀 정보는 가려집니다. 같은 키를 다른 본문에 재사용하면 idempotency_mismatch가 반환됩니다.

먼저 접근 카탈로그 읽기

통합에서 역할 권한을 하드 코딩하지 마세요. 초대하거나 접근 권한을 변경하기 전에 접근 카탈로그를 호출하세요. 카탈로그의 grantable 플래그는 호출자의 현재 구성원 자격을 반영하며, 소유자가 해당 자격을 조정하면 변경될 수 있습니다.

현재 새 초대에 제공되는 역할은 다음과 같습니다.

• client - 할당된 도메인과 메일함을 관리하지만 리셀러와 TrekMail의 비공개 관계는 볼 수 없습니다.
• webmail_only - 팀 목록에는 표시되지만 대시보드 권한은 받지 않습니다.
• domain_admin - 할당된 도메인과 해당 DNS를 관리하지만 메일함은 관리하지 않습니다.
• mailbox_operator - 할당된 도메인 안의 메일함을 관리하지만 도메인 자체는 관리하지 않습니다.
• read_only - 허용된 계정 영역을 살펴볼 수 있지만 변경할 수는 없습니다.
• custom - permissions에 나열된 권한만 받습니다.

일부 역할에는 명시적인 domain_ids가 필요하며, 다른 역할은 all_domains를 사용할 수 있습니다. 접근 카탈로그에서 적용되는 규칙을 확인할 수 있습니다. 호출자가 더 넓은 역할, 권한 또는 도메인 집합을 부여하려 하면 TrekMail은 초대 범위를 조용히 줄이지 않고 scope_blocked_by_membership을 반환합니다.

고객 초대

curl -s -X POST "https://trekmail.net/api/v1/white-label/members" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invite-northwind-admin-20260904" \
  -d '{
    "email": "admin@northwind.example",
    "role": "client",
    "all_domains": false,
    "domain_ids": [123, 124],
    "note": "Northwind primary contact"
  }'

응답에는 구성원, 이메일 전송 성공 여부, 일회성 초대 URL이 포함됩니다. 전송 문제가 생겨도 초대가 삭제되지는 않습니다. 소유자가 URL을 복사하거나 나중에 다시 보낼 수 있습니다.

사용자 지정 역할의 경우 접근 카탈로그에서 grantable_permissions를 읽고 선택한 값을 permissions로 보내세요. 적어도 하나의 권한이 필요합니다.

구성원 상태 추적

모든 구성원 응답에는 allowed_operations가 포함됩니다. 추측하지 말고 이 목록을 사용하세요.

• 대기 중인 초대는 업데이트, 일시 중지, 재전송 또는 제거할 수 있습니다.
• 활성 구성원은 업데이트, 일시 중지 또는 제거할 수 있습니다.
• 일시 중지된 구성원은 업데이트, 재개 또는 제거할 수 있습니다.
• 제거된 구성원은 복원할 수 있습니다.
• 소유자 행은 참고용으로 표시되지만 이 엔드포인트를 통해 변경할 수 없습니다.

이 목록은 현재 호출자에 맞게 필터링됩니다. 읽기 전용 연결, 호출자 자신의 구성원 자격, 호출자가 관리할 수 있는 범위보다 권한이 넓은 구성원에게는 목록이 비어 있습니다.

호출자는 자신을 제거하거나 일시 중지할 수 없습니다. 위임된 호출자는 자신보다 접근 권한이 넓은 구성원도 관리할 수 없습니다. 잘못된 전환은 구성원을 다시 읽으라는 안내와 함께 membership_state_conflict를 반환합니다.

사용자를 일시 중지하거나 제거하면 해당 구성원 자격으로 생성된 API와 메일함 키가 취소됩니다. 구성원 자격을 재개하거나 복원해도 이전 키는 되살아나지 않습니다. 해당 사용자는 다시 연결하거나 새 자격 증명을 만들어야 합니다.

활동과 개인정보 보호 경계

GET /white-label/activity는 초대, 역할과 도메인 변경, 일시 중지, 제거, 복원 및 관련 보안 작업을 반환합니다. action, member_id, per_page로 필터링할 수 있습니다.

GET /white-label/members/{id}/activity는 해당 구성원의 계정 작업과 최근 로그인을 함께 반환합니다. 여기에는 시간, IP 주소, 대략적인 위치, 브라우저, 운영 체제, 기기 유형이 포함됩니다. 이 경로는 의도적으로 두 읽기 범위를 모두 요구합니다. 도메인 제한이 있는 호출자는 자신의 도메인 경계에 완전히 포함된 구성원만 요청할 수 있습니다. 접근할 수 없는 구성원은 404로 반환되므로 이 엔드포인트는 다른 테넌트나 고객의 존재를 드러내지 않습니다.

MCP 도구

자체 호스팅 stdio MCP에서 초대 도구를 사용하려면 TREKMAIL_ALLOW_SENDING=true가 필요합니다. 접근 권한 변경 도구에는 TREKMAIL_ALLOW_DESTRUCTIVE=true가 필요하며, 제거에는 confirm_remove=true도 필요합니다. 이 스위치는 로컬 안전 제어이며 추가 API 권한이 아닙니다. 호스팅 MCP는 자체적으로 승인된 안전 정책을 적용합니다.

키를 제공하지 않으면 도구가 결정적 멱등성 키를 생성합니다. 워크플로가 다른 프로세스에서 다시 시작될 수 있다면 직접 idempotency_key를 제공하는 것이 유용합니다.

안전한 자동화 흐름

1. get_white_label을 호출합니다. scope_blocked_by_entitlement이면 중지하세요. 성공한 grace 응답에서는 읽기 작업만 계속하세요.
2. 접근 권한을 부여하기 직전에 get_white_label_access_catalog를 호출합니다.
3. 대상 구성원을 변경하기 전에 목록에서 찾거나 읽습니다.
4. allowed_operations, 의도한 역할, 권한, 도메인 ID를 확인합니다.
5. 쓰기 작업에 안정적인 멱등성 키를 사용합니다.
6. 구성원을 다시 읽고 결과 상태와 유효 권한을 보고합니다.
7. 변경에 대한 감사 기록이 필요하면 화이트 라벨 활동을 확인합니다.

다음 조치를 알려주는 오류