API 안전 보호 장치와 삭제 인텐트 가이드

TrekMail API는 우발적인 데이터 손실을 방지하도록 설계되었습니다. 파괴적 작업에는 여러 확인 단계가 필요하고, 속도 제한은 대량 작업 실수를 방지하며, 모든 작업이 기록됩니다.

휴지통. 사서함 삭제 인텐트를 확인하면 사서함을 즉시 파기하는 대신 7일간 보관되는 휴지통으로 이동합니다. 대시보드에는 최근 삭제됨으로 표시됩니다. 삭제된 사서함을 나열하고 기간 내에 하나를 복원할 수 있습니다.

GET  /api/v1/mailboxes?status=trashed        # list the recycle bin
POST /api/v1/mailboxes/{id}:restore          # restore to active (scope mailboxes:delete)

보존 기간이 지나면 일일 작업이 휴지통의 사서함을 영구적으로 삭제합니다. 복원할 때는 도메인별 사서함 한도를 다시 확인합니다. MCP 에이전트는 restore_mailbox 및 list_trashed_mailboxes 도구를 사용합니다. 이제 confirm_delete_intent는 복구할 수 있으며 되돌릴 수 없는 작업이 아닙니다. 도메인이나 계정을 삭제하면 해당 사서함은 영구적으로 제거되며 휴지통을 사용하지 않습니다.

2단계 삭제(삭제 인텐트)

사서함과 도메인 삭제는 API에서 가장 영향이 큰 파괴적 작업입니다. 2단계 절차를 사용합니다.

1단계: 삭제 인텐트 만들기

POST /api/v1/mailboxes/{id}:delete-intent

삭제할 대상을 설명하는 시간 제한 인텐트를 만듭니다. 응답에는 다음 항목이 포함됩니다.

• 위험 플래그: 영향을 받는 전달 규칙, 별칭 또는 활성 마이그레이션에 대한 경고입니다.
• 만료: 인텐트는 10분 후 만료됩니다. 그 후에는 새 인텐트를 만들어야 합니다.
• 확인 URL: 2단계에서 호출할 URL입니다.

이 단계에서는 데이터가 삭제되지 않습니다.

2단계: 인텐트 확인하기

POST /api/v1/delete-intents/{id}:confirm
Headers: X-Confirm-Delete: true

TrekMail 사서함 휴지통이 활성화된 경우 확인 작업은 사서함을 최근 삭제됨으로 이동하고 status: "executed"가 있는 완료된 인텐트를 반환합니다. 복원 시 도메인에 사서함을 추가할 여유가 있다면 7일 동안 복원할 수 있습니다.

{
  "id": 1,
  "mailbox_id": 4,
  "mailbox_email": "user@acme.test",
  "status": "executed",
  "risk_flags": [],
  "confirmed_at": "2026-05-28T11:22:08+00:00",
  "executed_at": "2026-05-28T11:22:08+00:00"
}

복구 기간이 지나면 TrekMail의 일일 정리 작업이 사서함을 영구적으로 제거합니다. 그 전에 휴지통 목록 또는 복원 엔드포인트를 사용하세요. 도메인이나 계정을 삭제할 때는 이 사서함 복구 경로를 사용하지 않습니다.

추가 안전 검사로 확인 요청에 X-Confirm-Delete: true 헤더가 반드시 필요합니다.

위험 플래그

삭제 인텐트를 만들면 API는 작업을 계속하지 않아야 할 수 있는 조건을 확인합니다.

확인하기 전에 이 플래그를 검토하세요. API는 위험 플래그를 근거로 확인을 차단하지 않습니다. 플래그는 정보 제공용입니다.

파괴적 작업의 속도 제한

파괴적 작업에는 표준 분당 API 속도 제한 외에도 두 단계의 제한이 있습니다.

• 토큰별 일일 한도: 각 토큰은 하루에 제한된 수의 삭제 인텐트만 확인할 수 있습니다.
• 확인 사이의 대기 시간: 한 삭제를 확인한 후 다음 확인이 수락되기까지 짧은 대기 시간이 있습니다.

두 제한 모두 트리거되면 Retry-After 헤더와 함께 429 Too Many Requests를 반환합니다.

로컬 호스팅 서버의 MCP 안전 제어

stdio MCP 서버를 직접 실행하는 경우 관리자는 삭제 도구를 사용하기 전에 TREKMAIL_ALLOW_DESTRUCTIVE=true를 요구할 수 있습니다. 이는 로컬 안전 제어이며 TrekMail 제품 기능을 켜고 끄는 설정이 아닙니다. 호스팅 MCP는 OAuth 중 승인된 권한을 사용합니다.

읽기 도구는 부여된 범위 내에서 계속 사용할 수 있습니다. 삭제 작업을 허용하기 전에 에이전트의 작업과 범위를 검토하세요.

멱등성

Idempotency-Key가 필요한 쓰기 엔드포인트는 엔드포인트 표와 OpenAPI 명세에 이를 표시합니다. 요청을 다시 시도하기 전에 논리적 작업마다 새 키를 사용하세요.

Idempotency-Key: create-mailbox-alice-2024

• 동일한 키와 동일한 본문은 작업을 반복하지 않고 원래 응답을 재생합니다.
• 동일한 키와 다른 본문은 409 Conflict를 반환합니다.
• 서로 다른 토큰은 독립적인 키 공간을 사용합니다.

MCP 서버는 도구 호출에 재시도해도 안전한 멱등성 키를 생성하므로 재시도가 이미 완료된 작업을 반복하지 않습니다.

전송 안전 게이트

MCP 서버를 통한 이메일 전송에는 파괴적 작업 게이트와 비슷하지만 두 가지 독립적인 검사를 사용하는 자체 이중 게이트 안전 설계가 있습니다.

게이트 1: 로컬 서버 제어

로컬 호스팅 MCP 서버에서는 send_message 도구를 허용하도록 TREKMAIL_ALLOW_SENDING=true를 설정하세요. 호스팅 MCP는 OAuth 중 승인된 권한을 사용합니다.

게이트 2: 호출별 확인

환경 게이트가 활성화되어 있어도 각 send_message 호출에는 confirm_send=true 매개변수가 포함되어야 합니다. 이 매개변수가 없으면 도구는 에이전트에게 확인을 요청하는 오류를 반환합니다.

게이트가 두 개인 이유

로컬 제어는 MCP 서버를 구성하는 관리자가 한 번 설정합니다. 호출별 제어는 에이전트가 각 이메일을 보낼지 적극적으로 결정하도록 요구합니다. 어느 한 제어만으로는 충분하지 않으며 이메일이 서버를 떠나기 전에 둘 다 통과해야 합니다.

이렇게 하면 사용 가능한 도구의 결과를 이해하지 못한 채 탐색하는 에이전트가 실수로 이메일을 보내는 것을 방지합니다. 에이전트는 메시지 토큰을 사용해 메시지를 자유롭게 나열하고 읽을 수 있지만 두 안전 게이트를 모두 충족하기 전에는 보낼 수 없습니다.

마이그레이션 안전 게이트

MCP 서버를 통한 이메일 마이그레이션에는 전송 및 파괴적 작업과 비슷한 자체 안전 게이트가 있습니다.

마이그레이션 로컬 서버 제어

로컬 호스팅 MCP 서버에서는 마이그레이션 쓰기 도구(start_migration, retry_migration, delete_migration)를 허용하도록 TREKMAIL_ALLOW_MIGRATION=true를 설정하세요. 호스팅 MCP는 OAuth 중 승인된 권한을 사용합니다.

cancel_migration은 이 설정과 관계없이 항상 사용할 수 있습니다. 통제할 수 없는 마이그레이션을 중지하기 위해 항상 접근할 수 있어야 하는 안전 작업입니다.

읽기 전용 마이그레이션 도구(list_migrations, get_migration)는 게이트 없이 작동합니다. test_migration_connection은 외부 IMAP 연결을 만들기 때문에 TREKMAIL_ALLOW_MIGRATION=true가 필요합니다.

마이그레이션 호출별 확인

각 마이그레이션 쓰기 도구에는 확인 매개변수가 필요합니다.

• start_migration에는 confirm_start=true가 필요합니다
• cancel_migration에는 confirm_cancel=true가 필요합니다
• retry_migration에는 confirm_retry=true가 필요합니다

확인 매개변수가 없으면 도구는 에이전트에게 확인을 요청하는 오류를 반환합니다.

서버 전체 동시 실행 한도

API는 동시 마이그레이션에 전역 한도를 적용합니다(기본값: 20). 한도에 도달하면 새 마이그레이션 요청은 migration_capacity_reached 및 retryable: true와 함께 503을 반환합니다. 많은 계정이 동시에 마이그레이션할 때 서버 리소스를 보호합니다.

감사 로그

데이터를 변경하는 모든 API 작업은 감사 로그에 기록되며 대시보드의 AI 에이전트 및 API → 감사 로그에서 볼 수 있습니다. 이벤트에는 다음이 포함됩니다.

• 토큰 생성 또는 취소: 누가 언제 작업 토큰을 생성하거나 취소했는지 기록합니다.
• 메시지 토큰 생성 또는 취소: 누가 메시지 토큰을 생성하거나 취소했는지 기록합니다.
• 인텐트 생성: 특정 사서함에 대한 삭제 인텐트가 생성되었습니다.
• 인텐트 확인: 삭제 요청이 수락되었습니다.
• 삭제 실행: 사서함이 최근 삭제됨으로 이동했고 복구 기간이 시작되었습니다.
• 인텐트 만료: 확인되지 않은 인텐트가 10분 후 만료되었습니다.
• 사서함 생성: API를 통해 새 사서함이 프로비저닝되었습니다.
• 초대 생성: 사서함 설정 초대가 전송되었습니다.
• 전달 업데이트: 사서함의 전달 규칙이 변경되었습니다.
• DNS 재검사 트리거: 도메인의 DNS 확인이 요청되었습니다.
• 마이그레이션 시작: API를 통해 이메일 마이그레이션이 시작되었습니다.
• 마이그레이션 취소: 실행 중인 마이그레이션이 취소되었습니다.
• 마이그레이션 재시도: 실패했거나 취소된 마이그레이션을 다시 시도했습니다.
• 마이그레이션 삭제: 마이그레이션 레코드가 삭제되었습니다.
• 메시지 읽음: 메시지 API를 통해 메시지가 나열되거나 읽혔습니다.
• 메시지 전송: 메시지 API를 통해 이메일이 전송되었습니다.
• 메시지 전송 실패: 이메일 전송 시도가 실패했습니다.
• 메시지 플래그 업데이트: 메시지 플래그(읽음/읽지 않음, 별표)가 변경되었습니다.
• 메시지 삭제: 사서함 폴더에서 메시지가 삭제되었습니다.
• 메시지 이동: 메시지가 폴더 간에 이동되었습니다.
• 도메인 생성: API를 통해 도메인이 추가되었습니다.
• 도메인 삭제: API를 통해 도메인이 제거되었습니다.
• 티켓 생성: API를 통해 지원 티켓이 열렸습니다.
• 티켓 답변: 티켓에 답변이 게시되었습니다.
• 티켓 종료: 티켓이 종료되었습니다.
• SMTP 구성: SMTP 설정이 업데이트되었습니다.
• SMTP 연결 삭제: 사용자 지정 SMTP 연결이 제거되었습니다.
• SMTP 테스트 대기열 등록: SMTP 연결 테스트가 시작되었습니다.
• Cloudflare 토큰 삭제: 저장된 Cloudflare 토큰이 API를 통해 제거되었습니다.

읽기, 전송, 플래그 업데이트, 삭제, 이동을 포함한 모든 메시지 API 이벤트가 완전히 기록됩니다. 감사 레코드는 90일 동안 보관됩니다.

각 이벤트는 사용된 토큰, 영향을 받은 리소스, IP 주소, 요청 ID를 기록합니다.

특정 활동을 조사하려면 이벤트 유형, 토큰 또는 날짜 범위로 감사 로그를 필터링하세요.

빠른 해결 방법

• 확인 전에 인텐트가 만료됨: 새 삭제 인텐트를 만드세요. 인텐트는 10분 후 만료됩니다.
• "Missing confirm header": 확인 요청에 X-Confirm-Delete: true 헤더를 추가하세요.
• 삭제 확인 시 429: 일일 한도 또는 대기 시간에 도달했습니다. Retry-After에 지정된 시간 동안 기다리세요.
• 자체 호스팅 MCP 에이전트가 삭제 도구가 비활성화되었다고 알림: 로컬 관리자가 해당 MCP 프로세스 환경에서 TREKMAIL_ALLOW_DESTRUCTIVE=true를 설정할 수 있습니다.
• 자체 호스팅 MCP 에이전트가 "Sending is disabled"라고 알림: 로컬 관리자가 해당 MCP 프로세스 환경에서 TREKMAIL_ALLOW_SENDING=true를 설정할 수 있습니다.
• MCP 에이전트가 "Send not confirmed"라고 알림: 에이전트는 send_message를 호출할 때마다 confirm_send=true를 매개변수로 전달해야 합니다.
• 자체 호스팅 MCP 에이전트가 마이그레이션 도구가 비활성화되었다고 알림: 로컬 관리자가 해당 MCP 프로세스 환경에서 TREKMAIL_ALLOW_MIGRATION=true를 설정할 수 있습니다.
• 503 "migration_capacity_reached": 서버 전체에서 너무 많은 마이그레이션이 실행 중입니다. 몇 분 기다린 후 다시 시도하세요.
• 409 "active migration running": 기존 마이그레이션을 취소하거나 완료될 때까지 기다린 후 새 마이그레이션을 시작하세요.