API 범위 및 요금제 권한 전체 가이드

범위는 API 토큰이 할 수 있는 작업을 정확히 제어합니다. 각 토큰은 범위 집합을 가지며 API는 모든 요청에서 이를 확인합니다.

범위의 작동 방식

토큰을 만들 때 포함할 범위를 선택합니다. API는 모든 요청에 세 가지 상한을 적용합니다.

1. 계정 권리: 현재 요금제와 활성 부가 기능이 지금 사용할 수 있는 기능을 결정합니다.
2. 멤버십: 위임된 사용자는 현재 역할과 도메인 접근 권한보다 더 많은 권한을 부여하거나 사용할 수 없습니다.
3. 자격 증명 부여: 토큰 또는 OAuth 동의에 엔드포인트가 요구하는 범위가 포함되어야 합니다.

오류는 통과하지 못한 상한을 알려 줍니다. insufficient_scope는 자격 증명에 범위가 부여된 적이 없음을, scope_blocked_by_membership은 사용자의 역할이 더 제한적임을, scope_blocked_by_entitlement는 필요한 White Label 권리가 활성 상태가 아님을 의미합니다.

두 가지 범위 계층: OAuth 및 API 범위

OAuth는 6개의 기존 편의 번들, 모든 세분화된 API 범위, 노출만 제어하는 tools:* 선택기를 지원합니다. 기존 번들은 다음과 같습니다.

각 기존 OAuth 번들은 domains:read 및 drive:account:write 같은 세분화된 API 범위로 확장됩니다. 새 통합은 이러한 범위를 직접 요청할 수 있습니다. White Label 범위는 이전 mail:* 번들에서 의도적으로 제외되므로 기존 커넥터가 업그레이드 후 리셀러 관리 권한을 얻지 않습니다. 필요한 White Label 범위를 명시적으로 요청해야 합니다. tools:white_label 선택기는 MCP 노출을 제한하지만 그 자체로 API 권한을 부여하지 않습니다.

세 가지 연결 방법과 기능 부여 방식

에이전트 또는 통합이 TrekMail에 연결하는 방법은 세 가지이며 각 방법의 게이트 메커니즘이 다릅니다. MCP "기능 플래그"(TREKMAIL_ALLOW_DESTRUCTIVE, TREKMAIL_ALLOW_SENDING, TREKMAIL_ALLOW_MIGRATION)는 그중 한 방법에만 존재하므로 중요합니다.

요약하면 호스팅 HTTP MCP는 OAuth 자격 증명에 따라 표시할 도구를 필터링하고, stdio MCP는 토큰 범위와 도구 집합, 읽기 전용 모드, 로컬 안전 제어의 교집합을 사용하며, REST API는 토큰의 세분화된 범위로 직접 제한됩니다. 모든 모드에서 런타임 API 권한 부여가 최종 결정권을 가집니다.

범위 참조

계정 및 청구

billing:autopay는 자금을 이동하는 유일한 범위이므로 내용을 주의 깊게 확인해야 합니다.

이 범위는 billing:read와 의도적으로 분리되어 있습니다. 청구서를 볼 수 있는 연결이 청구액을 늘릴 수 있어서는 안 되며, 청구 읽기 전용 권한은 지출 동의가 아닙니다. 이 범위는 자동으로 포함되지 않으며 명시적으로 부여한 토큰이나 연결만 가질 수 있고, 이전의 모든 넓은 범위 번들에 포함되지 않습니다. 따라서 이 범위가 생기기 전에 승인된 연결은 비용을 지출할 수 없습니다.

허용되는 작업은 이메일 검증 크레딧 구매와 구독 시작입니다. 기존 구독을 취소, 다운그레이드 또는 변경하는 작업은 전혀 허용되지 않습니다. 이러한 작업을 위한 엔드포인트가 없습니다. 범위를 가진 연결 수와 관계없이 전체 계정에 대해 구매별, 일별, 월별 지출 한도도 적용됩니다.

검증 크레딧은 Nano를 포함한 모든 요금제에서 판매되므로 이 범위도 모든 요금제에서 사용할 수 있습니다.

도메인

도메인 별칭 배달은 Starter부터 사용할 수 있습니다. Starter 토큰은 저장된 상태와 실시간 상태를 읽을 수 있지만 API/MCP로 연결, 변경 또는 제거하려면 Pro/Agency의 domains:write 기능이 필요합니다. Starter에서도 대시보드 변경은 계속 사용할 수 있습니다. API 및 MCP를 통한 도메인 별칭을 참조하세요.

White Label

이 운영 토큰 범위는 White Label 평가판 또는 유료 부가 기능이 활성 상태일 때만 나타납니다. 취소 유예 기간에는 소유자가 읽기 범위를 유지하지만 위임된 멤버와 모든 쓰기 범위는 제거됩니다.

실시간 멤버십도 또 다른 상한을 적용합니다. 고객이나 팀원이 더 넓은 토큰을 만들어 자신의 역할, 도메인 접근 권한 또는 사용자 지정 권한을 확장할 수 없습니다. API 및 MCP로 White Label 팀 관리를 참조하세요.

사서함

메시지(메시지 토큰)

메시지 범위는 운영 토큰(tm_live_ 접두사)이 아니라 메시지 토큰(tm_msg_ 접두사)에 포함됩니다. 메시지 토큰은 mailboxes:message-tokens:manage 범위를 가진 운영 토큰을 사용해 API로 만듭니다. 일반 전송 경로의 한도 외에도 API 전용 보호 기능이 있습니다. 기본적으로 읽기는 토큰마다 분당 30개 요청과 일일 5,000개의 성공한 읽기를 허용합니다. 전송은 토큰마다 분당 60개 요청과 사서함 전체에서 일일 100개의 API 전송을 허용합니다. 두 번째 토큰 안전 카운터는 기본적으로 일일 500개 전송이므로 일반적으로 더 낮은 사서함 한도가 적용됩니다.

모든 새 웹메일 API 엔드포인트(연락처, 캘린더, ID, 템플릿, 차단한 발신자, 초안, 예약 전송, 폴더, 첨부 파일)는 기존 세 가지 메시지 범위에 매핑되며 새 범위가 추가되지 않았습니다. 기존 토큰은 변경 없이 계속 작동합니다.

messages:read는 쓰기 접근을 부여하지 않습니다. 호스팅 OAuth에서 더 넓은 messages:send 기능을 승인하면 읽기, 쓰기, 전송 접근이 함께 프로비저닝됩니다. 수동으로 만든 tm_msg_ 토큰은 생성 시 선택한 범위만 정확히 유지합니다.

지원 티켓

Starter: API에서는 읽기 전용입니다. 대시보드에서 티켓을 열고 답변하세요.

SMTP 구성

SMTP는 도메인별로 구성되며(/api/v1/domains/{id}/smtp), 하나의 계정 전체 기본값(/api/v1/smtp/default)이 새 도메인의 시작 설정을 결정합니다. 전체 엔드포인트 목록은 API 개요를 참조하세요. 이전 계정 수준 /api/v1/smtp 엔드포인트는 호환성을 위해 계속 응답하지만 더 이상 경로를 제어하지 않습니다.

마이그레이션

마이그레이션 범위는 운영 토큰(tm_live_ 접두사)에 포함됩니다. Starter는 API에서 마이그레이션을 보고 대시보드에서 실행할 수 있습니다. Pro 및 Agency는 API와 MCP를 통해 마이그레이션을 시작, 취소, 재시도, 삭제할 수도 있습니다.

Cloudflare

Drive

Drive 범위는 운영 토큰 범위입니다. 토큰을 선택한 사서함으로 제한할 수 있으며 Drive는 해당 토큰에서 다른 사서함 공간을 숨깁니다. Drive 부가 기능 구매, 크기 변경, 취소는 API/MCP 쓰기 작업이 아니며 청구 변경은 대시보드에서 수행합니다.

Nano + Drive 부가 기능: 활성 Drive Storage 부가 기능이 있으면 Nano는 전체 Drive 범위 집합을 얻습니다. 다른 기능은 잠금 해제되지 않으며 Drive와 Nano가 이미 가진 이메일 검증 범위만 제공됩니다. 부가 기능을 취소하면 읽기 범위는 7일의 유예 기간 동안 계속 활성화되어 다운로드나 이전을 마칠 수 있습니다. 쓰기, 공유, 영구 삭제는 즉시 중단됩니다.

이메일 검증기

이메일 검증기 범위는 Nano를 포함한 모든 요금제에서 사용할 수 있습니다. 유일한 제한은 크레딧 잔액입니다. 전체 엔드포인트 참조는 이메일 검증기 API를 확인하세요.

요금제 접근 수준

White Label 범위는 추가 기능이며 기본 Pro 또는 Agency 요금제의 일부가 아닙니다. 해당 계정의 White Label 권리가 활성 상태일 때만 나타납니다.

다운그레이드 시 발생하는 작업

Pro에서 Starter로 다운그레이드해도 쓰기 범위를 가진 기존 토큰은 삭제되지 않습니다. 대신 API가 런타임에 허용되지 않는 범위를 사용하는 요청을 차단합니다.

예를 들어 Starter 요금제에서 mailboxes:create를 가진 토큰으로 사서함을 만들려고 하면 코드 token_scope_blocked_by_plan과 함께 403을 받습니다. 같은 토큰의 읽기 범위는 계속 작동합니다.

이 문제를 해결하려면 이전 토큰을 취소하고 현재 요금제에서 허용하는 범위만 가진 새 토큰을 만드세요.

위험한 범위

mailboxes:delete, domains:delete, migrations:write, cloudflare:delete 범위는 대시보드에서 위험한 것으로 표시됩니다. 이러한 범위를 가진 토큰은 사서함 또는 도메인 삭제를 시작하고, Cloudflare 토큰을 제거하거나, 기타 되돌릴 수 없는 작업을 수행할 수 있습니다. 사용 사례에 실제로 필요한지 검토하세요.

로컬 호스팅 MCP 서버에서는 삭제 도구를 사용할 수 있기 전에 관리자가 TREKMAIL_ALLOW_DESTRUCTIVE=true를 요구할 수 있습니다. 호스팅 MCP는 OAuth 중 승인된 범위를 사용합니다.

messages:send 범위는 사서함에서 실제 이메일을 보낼 수 있게 합니다. 로컬 호스팅 MCP 서버에서는 매번 보낼 때 TREKMAIL_ALLOW_SENDING=true 및 confirm_send=true도 요구할 수 있습니다. 자세한 내용은 안전 보호 장치와 삭제 인텐트를 참조하세요.

migrations:write 범위는 저장된 자격 증명으로 외부 IMAP 서버에 연결하는 이메일 마이그레이션을 시작할 수 있게 합니다. 로컬 호스팅 MCP 서버에서는 마이그레이션 쓰기에 TREKMAIL_ALLOW_MIGRATION=true 및 호출별 확인 매개변수(confirm_start, confirm_cancel, confirm_retry)도 요구할 수 있습니다.

도메인 제한

범위는 토큰이 무엇을 할 수 있는지 제어합니다. 도메인 제한은 어디에서 할 수 있는지 제어합니다.

특정 도메인으로 제한된 토큰은 해당 도메인 내의 리소스만 보고 수정할 수 있습니다. 다른 도메인을 노출하지 않고 계약자나 에이전트에게 단일 고객 도메인의 접근 권한을 제공할 때 유용합니다.

범위 검사는 도메인 제한 검사보다 먼저 수행됩니다. 토큰에 필수 범위가 없으면 도메인 제한과 관계없이 요청이 403으로 실패합니다.

빠른 해결 방법

• 403 "insufficient_scope": 토큰에 이 엔드포인트에 필요한 범위가 없습니다. 올바른 범위로 새 토큰을 만드세요.
• 403 "token_scope_blocked_by_plan": 요금제에서 더 이상 토큰의 범위 하나 이상을 허용하지 않습니다. 요금제를 업그레이드하거나 토큰을 취소하고 허용된 범위로 새 토큰을 만드세요.
• 403 "scope_blocked_by_entitlement": White Label이 비활성 상태이거나 취소 유예 기간에 쓰기를 시도했습니다. 연결을 다시 승인하기 전에 다시 활성화하세요.
• 403 "scope_blocked_by_membership": 현재 멤버 역할이나 사용자 지정 권한이 작업을 허용하지 않습니다. 계정 소유자에게 멤버십 변경을 요청하세요.
• 만들기 양식에 일부 범위가 숨겨짐: 요금제에서 해당 범위를 지원하지 않습니다. 허용된 범위만 표시됩니다.