TrekMail API 토큰 생성 및 관리 방법

API 토큰은 애플리케이션이나 에이전트가 계정에서 수행할 수 있는 작업을 제어합니다. 각 토큰에는 이름, 범위, 선택적 도메인 제한 및 만료일이 있습니다.

MCP 클라이언트를 연결하나요? 브라우저 인증을 지원한다면 https://trekmail.net/mcp를 원격 MCP 서버로 추가하고 브라우저에서 접근을 승인하세요. 일반적으로 토큰을 만들거나 붙여 넣을 필요가 없습니다. 수동 tm_live_ 토큰은 스크립트, CI 작업, 자체 호스팅 MCP 및 이 흐름을 지원하지 않는 클라이언트용입니다. AI 에이전트 연결 (MCP)을 참조하세요.

시작하기 전에

• Nano를 포함한 모든 요금제에서 API 토큰을 만들 수 있습니다. Nano 요금제는 Email Verifier 범위 (verify:read, verify:write)로 제한됩니다.
• Starter 요금제는 읽기 전용 인프라 범위와 전체 Drive 및 Email Verifier 범위를 제공합니다. Starter에서도 대시보드로 전달을 관리할 수 있지만, API 전달 쓰기 접근 (mailboxes:forwarding:write)에는 Pro 또는 Agency가 필요합니다. Pro와 Agency에서는 모든 범위를 사용할 수 있습니다.
• 소유자는 모든 계정 자격 증명을 관리할 수 있습니다. API 토큰 권한이 있는 위임 구성원은 자신이 만든 자격 증명만 관리할 수 있고, 구성원 자격에 이미 포함된 범위와 도메인만 부여할 수 있습니다.
• 팁: AI 에이전트 및 API 페이지에서 둘러보기 시작을 클릭하여 연결 옵션, 토큰, 연결된 앱 및 감사 로그에 대한 짧은 안내를 확인하세요.

Drive 자동화 토큰 만들기

Drive API와 MCP 도구는 작업 토큰 (tm_live_...)을 사용합니다. 워크플로에 필요한 Drive 범위만 선택하세요.

• 읽기 전용 보고: drive:account:read, drive:mailbox:read 또는 drive:addon:read.
• 업로드 자동화: drive:account:write 또는 drive:mailbox:write 추가.
• 공개 전달 링크: drive:account:share 또는 drive:mailbox:share 추가.
• 영구 정리: drive:account:purge 또는 drive:mailbox:purge는 별도로 엄격하게 관리되는 토큰에서만 사용.

Drive Add-on 구매, 크기 조정 및 취소는 API 토큰으로 수행할 수 없습니다. 에이전트는 drive:addon:read로 Add-on 상태와 가격을 읽을 수 있지만, 구독 변경은 대시보드에서 해야 합니다.

White Label 자동화 토큰 만들기

White Label은 branding:read, branding:write, members:read, members:write, activity:read의 다섯 가지 작업 토큰 범위를 사용합니다. 계정에 White Label 접근 권한이 있는 동안에만 표시됩니다. members:write는 접근 권한을 제거하고 다른 사람의 키를 취소할 수 있으므로 위험한 범위로 표시됩니다.

읽기 전용 상태 및 감사 통합에는 branding:read, members:read, activity:read를 선택하세요. 브랜드 및 DNS 설정에만 branding:write를 추가하세요. 자동화가 사람을 초대하거나 변경해야 할 때만 members:write를 추가하세요.

취소 유예 기간 동안 소유자는 복구용 읽기 범위 세 개를 유지하지만, 쓰기 작업과 위임된 White Label 자격 증명은 작동을 멈춥니다. 재활성화해도 취소된 자격 증명은 복구되지 않으므로 새 자격 증명을 만들거나 승인하세요.

토큰 만들기

1. AI 에이전트 및 API → 토큰으로 이동합니다.
2. 토큰 만들기를 클릭합니다.
3. 양식을 작성합니다.
   • 이름: 토큰을 식별할 레이블입니다. 예: "Claude 에이전트", "CI/CD 파이프라인".
   • 만료: 7일, 30일, 90일, 사용자 지정 날짜 또는 만료 없음 중에서 선택합니다.
   • 범위: 토큰이 수행할 수 있는 작업을 선택합니다. 허용된 모든 범위가 기본적으로 선택됩니다.
   • 도메인 제한: "모든 도메인"을 선택하거나 특정 도메인을 선택하여 토큰의 접근을 제한합니다.
4. 토큰 만들기를 클릭합니다.

생성 후 일반 텍스트 토큰은 한 번만 표시됩니다. 즉시 복사하거나 다운로드 버튼을 사용해 .txt 파일로 저장하세요.

토큰은 다시 볼 수 없습니다. 확인 창을 닫기 전에 안전하게 저장하세요.

메시지 토큰 만들기

메시지 토큰을 사용하면 에이전트가 특정 메일함에서 메일을 읽고 보낼 수 있습니다. 작업 토큰과 별개이며, 작업 토큰을 사용해 API를 통해 프로그래밍 방식으로 생성합니다.

메시지 토큰을 만들려면 에이전트가 다음을 호출합니다.

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

워크플로에 필요한 최소 범위를 선택하세요.

일반 텍스트 토큰 (tm_msg_...)은 한 번만 반환됩니다. MCP 구성에 TREKMAIL_MESSAGE_TOKEN으로 추가하세요.

메시지 토큰은 Pro 및 Agency 요금제에서 사용할 수 있습니다. 작업 토큰에는 mailboxes:message-tokens:manage 범위가 있어야 합니다.

연결된 Gmail 또는 다른 외부 받은편지함에는 external_account_id를 사용하세요. 수신자에게 승인된 비즈니스 주소를 표시하려면 ID endpoint에서 반환된 identity_id도 사용하세요. API 및 MCP에서 다른 이름으로 보내기 주소 사용을 참조하세요.

토큰 형식

TrekMail은 토큰 유형을 구분하기 위해 두 가지 토큰 접두사를 사용합니다.

접두사 뒤의 처음 8자는 쉽게 식별할 수 있도록 대시보드에 표시되는 접두사로 저장됩니다.

범위

범위는 토큰이 수행할 수 있는 작업을 제어합니다. 선택할 수 있는 항목은 요금제에 따라 다릅니다.

• Nano: Email Verifier (verify:read, verify:write)만 제공됩니다. Drive Storage를 추가하면 계정에서 사용할 자격이 있는 Drive API 및 MCP 기능도 제공됩니다.
• Starter: Drive와 Email Verifier 전체 접근 및 나머지 모든 항목(도메인, 메일함, 전달, 메일 필터, 자동 회신, 마이그레이션, 티켓, SMTP, Cloudflare)에 대한 읽기 전용 접근이 제공됩니다. 마이그레이션 만들기, 티켓에 답변하기, 자동 회신 변경 등 Starter가 API로 제공하지 않는 쓰기 작업에는 대시보드를 사용하세요.
• Pro 및 Agency: 전체 접근이 제공됩니다. 모든 기능군에서 읽기, 쓰기, 생성 및 삭제를 수행하고, API를 통한 이메일 읽기 및 전송용 메시지 토큰도 사용할 수 있습니다.

White Label 범위는 Add-on 권한이며 요금제 표를 우회하는 수단이 아닙니다. White Label이 활성 상태일 때만 제공되며, 취소 유예 기간 동안 소유자는 읽기 전용 복구 접근을 유지합니다.

각 범위에 대한 설명은 API 범위 및 요금제 권한을 참조하세요.

도메인 제한

기본적으로 토큰은 계정의 모든 도메인에 접근할 수 있습니다. 토큰을 특정 도메인으로 제한하려면 다음을 수행하세요.

1. 도메인 제한 섹션에서 선택한 도메인을 선택합니다.
2. 토큰이 접근할 도메인을 선택합니다.

제한된 토큰이 다른 도메인의 리소스에 접근하려 하면 404 응답을 받습니다. API는 해당 도메인이 존재하지 않는 것처럼 동작합니다.

토큰 취소하기

1. AI 에이전트 및 API → 토큰으로 이동합니다.
2. 목록에서 토큰을 찾습니다.
3. 취소를 클릭합니다.
4. 취소를 확인합니다.

취소된 토큰은 즉시 작동을 멈춥니다. 취소된 토큰을 사용하는 모든 API 요청은 401 Unauthorized를 받습니다.

취소는 영구적이며 되돌릴 수 없습니다. 접근을 복원해야 한다면 새 토큰을 만드세요.

토큰 상태

토큰에는 세 가지 상태가 있습니다.

토큰 페이지의 상태 필터를 사용해 상태별로 토큰을 표시하세요.

감사 추적

모든 토큰 생성 및 취소는 감사 로그 탭에 표시됩니다. 이벤트에는 토큰 이름, 작업 및 시간이 포함됩니다.

빠른 해결 방법

• "요금제에서 사용할 수 없는 범위": 요금제에 해당 범위가 포함되어 있지 않습니다. Nano는 verify:read와 verify:write로 제한됩니다(drive:* 범위도 사용하려면 Drive Storage Add-on을 추가하세요). Starter는 모든 인프라 기능군에 대한 읽기 접근과 전체 Drive 및 Email Verifier 접근을 제공합니다. Pro와 Agency에서는 모든 쓰기가 허용됩니다.
• 일반 텍스트 토큰 분실: 토큰을 복구할 수 없습니다. 취소하고 새로 만드세요.
• 토큰은 작동하지만 일부 도메인에서 404 반환: 토큰에 도메인 제한이 있을 수 있습니다. 취소한 뒤 "모든 도메인"으로 다시 만들거나, 누락된 도메인을 제한에 추가하세요.
• White Label 범위가 scope_blocked_by_entitlement 반환: White Label을 재활성화한 후 필요한 범위의 자격 증명을 만들거나 승인하세요.
• 역할 변경 후 위임 토큰이 중지됨: 구성원 접근을 축소, 일시 중지 또는 제거하면 영향을 받는 자격 증명이 즉시 취소됩니다. 소유자가 올바른 접근을 복원한 후 새 토큰을 만드세요.