API와 MCP로 메일 앱 비밀번호 관리

REST API와 MCP는 일반 메일함의 앱 비밀번호를 조회, 생성, 교체, 취소하고 메일 앱 로그인 방식을 변경하며 향후 메일함의 계정 기본값을 설정할 수 있습니다. 이 페이지는 연동을 위한 참조 문서입니다. 대시보드와 웹메일 사용법은 기기별 메일 앱 비밀번호 만들기와 관리를 참조하세요.

앱 비밀번호는 IMAP, SMTP 포트 465 및 587, ManageSieve, CalDAV/CardDAV에 사용할 수 있습니다. 새 웹메일이나 대시보드를 열 수 없습니다. 클래식 웹메일은 IMAP으로 로그인하며 앱 비밀번호를 허용합니다. 메일함 2FA는 새 웹메일 로그인만 보호합니다. 메일 앱과 클래식 웹메일은 해당 코드를 요청하지 않습니다.

이 기능에는 별도의 메일함 요금제 제한이 없습니다. 기존 API 및 MCP 요금제 권한은 계속 적용됩니다. API 범위 및 권한을 참조하세요.

인증, 범위 및 구성원 권한

/api/v1 아래의 REST 요청에 Bearer 토큰을 사용하세요. JSON 쓰기 요청에는 Content-Type: application/json과 Idempotency-Key 헤더를 사용합니다.

토큰의 API 범위 외에도 구성원 역할의 비밀번호 설정 권한을 확인합니다. 구성원 토큰과 구성원이 승인한 커넥터에 적용됩니다. 소유자의 토큰에는 추가 비밀번호 설정 범위가 필요하지 않습니다. 구성원 권한이 없으면 403 scope_blocked_by_membership을 반환합니다.

호스팅된 OAuth 커넥터는 대응하는 REST 기능 범위를 사용할 수 있습니다. 기존 범위 묶음에서는 mail:read가 mailboxes:read와 account:read를 제공하고 mail:write는 mailboxes:write도 제공합니다. 범위 확장은 구성원 권한이나 소유자 전용 규칙을 무시하지 않습니다.

일괄 선택을 포함해 토큰의 domain_ids 및 mailbox_ids 제약이 적용됩니다. 기능이 꺼져 있으면 앱 비밀번호 엔드포인트와 두 방식 변경 엔드포인트는 인증 및 미들웨어 검사 후 404 not_found를 반환합니다. 접근할 수 없거나 존재하지 않는 메일함도 404를 반환하므로 모든 404를 기능 상태의 신호로 해석하지 마세요.

엔드포인트 한눈에 보기

아래 경로에는 /api/v1 접두사가 포함됩니다. {mailbox}는 일반 메일함 ID이고 {id}는 해당 메일함에 속한 앱 비밀번호 행 ID입니다.

이 표의 모든 쓰기 요청에는 Idempotency-Key가 필요합니다. 비밀번호 엔드포인트는 기존 관리자 재설정 작업이며 앱 비밀번호 교체와는 별개입니다.

앱 비밀번호 목록과 행 필드 이해하기

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

응답의 최상위에는 mailbox_id, client_auth_mode, limit, active_count와 행 배열인 data가 있습니다. limit은 메일함당 활성 비밀번호 25개입니다. 활성 행이 먼저 표시되며 최신순으로 정렬됩니다. 취소된 행은 90일 동안 표시됩니다. 목록 응답에는 비밀 값이 포함되지 않습니다.

각 행에는 다음 필드가 포함됩니다.

공개 취소 사유는 revoked, rotated, mailbox_password_reset, mailbox_password_changed, login_suspended, converted_to_shared, mailbox_trashed입니다. 목록에는 플랫폼 내부에서 발급한 자격 증명이 포함되지 않습니다.

앱 비밀번호 만들기

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

name은 필수이며 표시 가능한 문자 1~64자여야 합니다. 연속된 공백은 하나로 합쳐집니다. 메일함은 로그인이 중지되지 않은 활성 일반 메일함이어야 하며 활성 앱 비밀번호가 25개 미만이어야 합니다.

201 응답에는 data 아래에 전체 행이 포함되고 **data.password**가 추가되며 message도 포함됩니다. 다음은 해당 응답 안의 자격 증명 필드 예시입니다.

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

이 예시는 위에서 설명한 다른 행 필드를 생략합니다. 비밀 값은 설명용입니다. 실제 값은 생성된 영문 소문자 16자이며 공백 없이 반환됩니다. 앱은 공백과 대문자도 허용하므로 사용자에게 표시할 때는 4자씩 네 묶음으로 보여 줄 수 있습니다.

비밀번호는 한 번만 반환됩니다. 애플리케이션 로그에 기록하지 마세요. 사용자는 전체 메일함 주소를 사용자 이름으로 사용하고 비밀번호를 메일 앱에 직접 입력합니다. 생성 및 교체 시 메일함과 설정된 복구 이메일에 앱 비밀번호의 이름이 포함된 알림이 전송되며 비밀 값은 포함되지 않습니다. 단, 새 메일함과 함께 발급되는 첫 앱 비밀번호는 예외입니다(아래 참조).

연결 설정에는 메일 클라이언트 설정 API를 사용하세요. 다운로드한 Apple 프로파일에는 비밀번호가 없습니다. 설치 중 macOS 또는 iOS가 요청할 때 사용자가 앱 비밀번호를 입력합니다.

새 메일함과 함께 첫 앱 비밀번호 받기

POST /api/v1/mailboxes와 POST /api/v1/mailboxes:bulk는 선택적 불리언 값 **create_app_password**를 허용합니다. true로 지정하면 생성된 각 메일함에 첫 앱 비밀번호도 발급되며 **app_password**로 한 번만 반환됩니다. 내용은 위에서 설명한 행 필드에 password를 더한 것입니다. 이름은 Created with the mailbox이며, 메일함이 새로 만들어졌고 호출자가 방금 비밀번호를 받았으므로 알림 이메일은 전송되지 않습니다. 이 필드를 생략하면(기본값 false) 응답은 바뀌지 않습니다. 앱 비밀번호가 활성화되지 않은 동안에는 무시됩니다.

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

이 경우 201 응답에는 웹메일용 메일함 비밀번호인 one_time_password와 메일 앱용 app_password.password가 포함됩니다. 일괄 응답에서는 생성된 각 행에 고유한 app_password가 있습니다. 발급하지 못한 경우 app_password는 null이며(단일 생성에서는 _app_password_warning도 추가됨), 메일함은 그대로 생성되므로 위의 엔드포인트로 앱 비밀번호를 만들 수 있습니다. 같은 Idempotency-Key로 단일 생성을 그대로 재시도하면 두 비밀 값을 모두 포함한 같은 응답이 반환되며 두 번째 앱 비밀번호는 발급되지 않습니다. 일괄 요청을 재실행하면 one_time_password와 마찬가지로 비밀 값이 생략됩니다.

비밀번호 교체 또는 취소

교체에는 JSON 본문이 필요하지 않습니다.

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

200 응답에는 data 아래의 새 전체 행, 한 번만 반환하는 data.password, 이전 행을 가리키는 최상위 replaced_id, message가 포함됩니다. 교체 행에는 **새 data.id**가 부여되며 이름은 유지됩니다. 이전 행은 revoked_reason: "rotated"로 취소되고 비밀 값은 즉시 무효화되며 이를 사용하던 앱은 로그아웃됩니다. 기기에 교체한 비밀번호를 입력하세요.

새 비밀번호를 발급하지 않고 취소하려면 다음을 사용하세요.

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

본문은 필요하지 않습니다. 200 응답에는 status: "revoked"와 data 아래의 전체 취소 행이 포함됩니다. 앱은 접근 권한을 잃으며 유효한 앱 비밀번호를 가진 다른 기기는 자동으로 다시 연결됩니다. 취소는 되돌릴 수 없습니다. 이미 취소된 행을 새 요청으로 교체하거나 취소하면 409 conflict를 반환합니다.

메일함 하나의 메일 앱 로그인 방식 변경

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

mode는 필수이며 다음 값을 허용합니다.

• app_password_only: 메일 앱에 앱 비밀번호를 요구합니다. 메일함 비밀번호를 쓰는 연결은 로그아웃되며 유효한 앱 비밀번호를 쓰는 앱은 자동으로 다시 연결됩니다.
• password_or_app_password: 메일 앱이 메일함 비밀번호 또는 앱 비밀번호를 허용합니다.

200 응답에는 mailbox_id, client_auth_mode, message가 포함됩니다. 현재 방식을 다시 설정하면 200을 반환하고 아무것도 바꾸지 않습니다. 방식 변경은 기존 앱 비밀번호를 취소하지 않습니다.

앱 비밀번호를 요구하기 전에 기기용 비밀번호를 만드세요. 메일함 비밀번호 로그인이 거부되면 "Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords."(로그인에 실패했습니다. 이 메일함은 앱 비밀번호만 허용합니다. 웹메일의 설정 > 앱 비밀번호에서 만드세요.)라는 오류가 표시될 수 있습니다. 일부 앱은 일반적인 비밀번호 오류만 표시합니다.

공유 메일함은 직접 로그인할 수 없으며 이 엔드포인트에서 422 mailbox_not_eligible을 반환합니다. 플랫폼 시스템 메일함은 app_password_only로 변경할 수 없으며 시도하면 422 system_mailbox_protected를 반환합니다.

어느 방식도 새 웹메일 로그인, 전체 받은편지함, Message API 토큰, 메일함으로 가져오기, 메일 규칙 또는 전달을 바꾸지 않습니다. 공유 메일함 구성원은 자신의 일반 메일함 자격 증명과 방식을 사용합니다.

방식 일괄 변경

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

mode와 정확히 하나의 선택 조건을 지정하세요.

계정 및 토큰 제약으로 모든 선택 범위가 좁혀집니다. 접근 범위 밖의 ID나 알 수 없는 ID를 명시하면 일부만 적용하는 대신 404를 반환합니다. 알 수 없거나 다른 계정의 도메인은 422 validation_error를 반환합니다. 선택 조건이 없거나 여러 개이면 422 invalid_selection을 반환합니다.

일치하는 메일함은 최대 1000개입니다. 더 큰 선택은 변경 전에 422 selection_too_large를 반환합니다. 도메인 범위를 좁히거나 명시적 ID 배치로 나누어 보내세요.

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

matched는 선택된 메일함 수, updated는 실제 방식 변경 수, skipped는 공유, 삭제된 항목으로 이동한 메일함 또는 삭제 중인 메일함 수입니다. 앱 비밀번호를 요구하는 경우 플랫폼 시스템 메일함도 skipped에 포함됩니다. 일시 중지되거나 로그인이 중지된 메일함도 접근이 복원될 때를 위해 방식을 업데이트할 수 있습니다. 이미 일치하는 메일함은 matched에는 포함되지만 updated나 skipped에는 포함되지 않으므로 작업을 안전하게 반복할 수 있습니다. 중지된 계정은 403으로 거부됩니다.

메일함 상태 읽기와 계정 기본값 설정

앱 비밀번호 기능이 켜져 있으면 GET /api/v1/mailboxes와 GET /api/v1/mailboxes/{mailbox}의 메일함 리소스에 다음 필드가 포함됩니다.

• client_auth_mode: app_password_only 또는 password_or_app_password.
• app_passwords_count: 표시 대상인 활성 앱 비밀번호의 정수 건수. 플랫폼 내부 자격 증명은 제외합니다.

기능이 꺼져 있으면 두 필드는 생략됩니다. 공유 메일함에는 사용 가능한 직접 로그인 방식이나 앱 비밀번호가 없으므로 일반 구성원 메일함의 자격 증명을 요청하세요.

GET /api/v1/account에는 account:read가 필요합니다. 일반 최상위 필드는 계속 제공됩니다. id, name, email, plan, effective_plan_slug, subscription_status, limits, features, usage, safety_limits, created_at입니다. 앱 비밀번호 기능이 켜져 있고 동시에 플랫폼이 새 메일함에 계정 기본값을 적용할 때만 **new_mailbox_client_auth_mode**가 추가됩니다. 그 외에도 GET은 사용 가능하지만 해당 필드는 생략됩니다.

계정 소유자만 기본값을 변경할 수 있습니다.

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

필수 필드는 동일한 두 방식을 허용합니다. 여기서 쓸 수 있는 계정 필드는 이것뿐입니다. 응답의 최상위에는 id, new_mailbox_client_auth_mode, message가 포함됩니다. 필드를 공개하는 두 조건이 모두 충족되지 않으면 PATCH는 404를 반환하며, 구성원 토큰이나 구성원이 승인한 커넥터에는 403 scope_blocked_by_membership을 반환합니다.

소유자의 토큰도 domain_ids 또는 mailbox_ids로 제한되면 403 token_resource_constrained를 반환합니다. 리소스 제한이 없는 소유자의 토큰을 사용하거나 계정 설정에서 기본값을 변경하세요.

기본값은 향후 대시보드, 일괄 생성, 초대, API 및 에이전트로 만드는 메일함에 적용되며 기존 메일함은 바꾸지 않습니다. API로 메일함 하나를 만들 때 POST /api/v1/mailboxes에 client_auth_mode를 명시할 수 있으며 생략하면 계정 기본값을 따릅니다. 기능 도입 시 기존 메일함은 password_or_app_password를 유지합니다. 계정 소유자가 변경하지 않는 한 새 메일함 기본값은 app_password_only입니다.

메일함 비밀번호 재설정 시 앱 비밀번호 자동 취소

POST /api/v1/mailboxes/{mailbox}/password에는 mailboxes:write, 동일한 구성원 비밀번호 설정 권한, Idempotency-Key가 필요합니다. 본문의 필수 필드 password에는 메일함 비밀번호 정책을 따르는 새 메일함 비밀번호를 지정합니다. 앱 비밀번호 생성 엔드포인트가 아닙니다.

이 엔드포인트를 통한 관리자 재설정이 성공하면 MCP 에이전트의 비밀번호 변경을 포함해 모든 앱 비밀번호가 mailbox_password_reset 사유로 취소됩니다. 취소를 제외하는 옵션은 없습니다. 기능이 켜져 있으면 응답에는 status, sync_pending, message와 함께 정수 건수인 app_passwords_revoked가 포함됩니다.

• 메일 서버 동기화가 완료되면 200, status: "updated", sync_pending: false.
• 비밀번호가 저장되고 동기화가 대기 중이면 202, status: "update_pending", sync_pending: true. 이 시점에 앱 비밀번호는 이미 취소된 상태입니다.

재설정은 기존 메일함 메시지 토큰도 취소합니다. 이는 메일함 비밀번호 재설정의 결과이며 개별 앱 비밀번호 교체나 메일 앱 방식 변경 때문이 아닙니다.

웹메일의 셀프서비스 비밀번호 변경은 사용자가 모든 앱 비밀번호도 취소를 선택할 때만 앱 비밀번호를 취소합니다. 비밀번호 복구, 로그인 중지, 공유 메일함 전환 및 최근 삭제된 항목으로 이동하면 모두 취소됩니다. 접근이나 메일함을 복원해도 취소된 비밀 값은 돌아오지 않습니다. API로 메일함 로그인 중지하기를 참조하세요.

멱등성과 한 번만 반환하는 비밀 값

의도한 쓰기 작업마다 새 Idempotency-Key를 사용하고 동일한 메서드, 경로 및 본문의 통신 재시도에만 재사용하세요. 키는 필수이며 최대 255자입니다. 성공 응답은 기본 24시간 동안 캐시되며 다른 요청에 같은 키를 재사용하면 409 idempotency_mismatch를 반환합니다.

앱 비밀번호 생성이나 교체 요청을 재실행하면 동일한 안전한 식별자를 반환하지만 data.password는 생략됩니다. _idempotency_replay_warning과 응답 헤더 X-Idempotency-Replayed: true가 포함됩니다. 재실행으로 잃어버린 비밀 값을 복구할 수 없습니다. 반환된 data.id로 새 키를 사용해 활성 행을 교체하고 사용 가능한 새 비밀번호를 얻으세요. 교체 후 새 ID를 추적하세요.

성공한 취소를 같은 키로 재실행하면 저장된 결과를 반환합니다. 해당 취소 행에 새 취소 요청을 보내면 409 conflict를 반환합니다. 방식 변경은 반복해도 같은 결과를 내지만 의도한 변경마다 새 키를 사용하세요. 방식을 바꾼 뒤 이전 키를 재사용하면 새 의도를 적용하는 대신 이전 응답을 다시 반환할 수 있습니다.

요청 한도와 오류

생성은 계정당 시간당 60회, 교체는 계정당 시간당 30회로 제한됩니다. 이 계정 한도는 API와 MCP 호출자가 공유하며 토큰별로 별도 제공되지 않습니다. 일괄 방식 변경에는 추가로 분당 10개 요청 제한이 적용됩니다. 일반 API 제한도 해당 경로에 적용되며 기본값은 자격 증명당 분당 60개 요청입니다. 제한된 요청은 429 rate_limited를 반환합니다. 재시도 전에 Retry-After 헤더를 따르세요.

오류는 code, message, hint, request_id, retryable을 포함하는 표준 error 객체를 사용합니다. 문구를 비교하는 대신 기계가 읽을 수 있는 코드로 처리하세요.

MCP 도구와 파괴적 작업 제어

MCP는 REST와 같은 권한 검사 및 응답 필드를 사용합니다. 직접 작업하는 도구는 다음과 같습니다.

메일함 생성 도구인 create_mailbox_generated_password와 bulk_create_mailboxes도 REST와 동일한 선택적 create_app_password 입력을 허용합니다.

쓰기 도구는 선택적인 idempotency_key도 허용합니다. REST는 메일함 방식 변경에 본문 필드 mode를 사용하고 MCP 도구는 해당 입력을 **client_auth_mode**라고 부릅니다. 일괄 선택 조건에는 REST와 동일한 접근 규칙 및 1000개 메일함 한도가 적용됩니다.

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

자체 호스팅 서버에서는 위의 모든 쓰기 작업에 **TREKMAIL_ALLOW_DESTRUCTIVE=true**가 필요합니다. 자격 증명 생성도 메일함 접근을 부여하므로 제어 대상입니다. 목록 조회와 계정 읽기에는 이 플래그가 필요하지 않습니다. 쓰기 도구를 호출하기 전에 의도한 자격 증명 또는 접근 변경에 대해 사용자 승인을 요청하세요. 비밀 값을 직접 반환하는 도구는 에이전트에게 비밀번호를 한 번만 보여 주고 사용자가 앱에 붙여 넣도록 하며, 파일이나 메모리에 저장하거나 이후 메시지나 도구 호출에서 반복하지 않도록 지시합니다.

ChatGPT/OpenAI 및 Claude 디렉터리 프로필

이 프로필은 채팅에서 비밀 값을 발급하는 대신 생성 및 교체를 위한 안전한 대시보드 설정 링크를 제공합니다. 이 프로필에서는 메일함 생성도 대시보드 링크로 처리되므로 첫 앱 비밀번호는 create_app_password가 아니라 대시보드의 메일함을 만들었습니다 카드에서 받습니다. 목적지는 /app/mailboxes/{mailbox_id}/security#app-passwords이며 사용자가 로그인하여 작업을 완료합니다.

OpenAI 프로필은 **get_mailbox_app_password_setup_link**와 **get_mailbox_app_password_replacement_setup_link**를 제공합니다. Claude 프로필은 **create_mailbox_app_password**와 rotate_mailbox_app_password 이름을 유지하지만 data.password 대신 안전한 설정 링크를 반환합니다. 해당 디렉터리 도구가 비밀 값을 반환한다고 약속하거나 사용자에게 대화에 붙여 넣도록 요청하지 마세요.

연결 정보에는 get_mail_client_setup을 사용하세요. 일반 커넥터 설정은 AI 에이전트 연결하기를 참조하세요. White Label 메일함은 동일한 API 기능과 브랜드 웹메일 및 메일 호스트를 사용합니다. 사용자 안내에서는 자격 증명을 앱 비밀번호라고 부르세요.