API로 메일함 로그인 일시 중지하기

로그인을 일시 중지하면 메일함 자체는 계속 작동하지만 사용자는 해당 메일함에 들어갈 수 없습니다. 메일은 평소처럼 배달되어 사용자를 기다리며, 반송되거나 손실되지 않습니다. 이 페이지에서는 이 설정에 사용하는 명령을 설명합니다.

같은 제어 기능은 대시보드의 메일함 → (메일함 하나) → 한도에 있습니다. 모든 요금제에서 추가 비용 없이 사용할 수 있습니다.

로그인 일시 중지와 메일함 일시 중지는 다른 호출

요금을 납부하지 않은 고객, 계약 사이의 공백 기간에 있는 사람 또는 계속 메일을 받아 두어야 하는 사용자에게는 :suspend-login을 사용하세요. 발신자의 메일까지 포함해 메일함 전체를 멈춰야 할 때는 :pause를 사용하세요.

두 호출로 설정할 수 없는 세 번째 상태도 있습니다. 발신 활동에서 메일함 비밀번호가 오용된 것으로 판단되면 TrekMail은 로그인과 수신을 그대로 둔 채 해당 메일함의 발송만 중지할 수 있습니다. 이때 발송 요청은 403 mailbox_sending_paused를 반환합니다. :resume과 :resume-login 어느 쪽으로도 해제할 수 없고 호출을 반복해도 바뀌지 않습니다. 비밀번호를 변경한 뒤 지원팀이 발송을 다시 켜야 합니다. 이메일을 보낼 수 없는 이유를 참조하세요.

필요한 범위

다른 메일함 필드를 업데이트할 때와 같은 mailboxes:write 범위가 필요합니다. 아래의 모든 endpoints는 Idempotency-Key 헤더를 받습니다.

메일함 하나

curl -s -X POST "https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}:suspend-login" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: suspend-{MAILBOX_ID}-invoice-42" \
  -d '{"reason":"Unpaid invoice 42"}'

{ "status": "login_suspended", "message": "Sign-in has been suspended. The mailbox keeps receiving mail." }

reason은 선택 사항이며 최대 255자까지 입력할 수 있습니다. 대시보드에 표시되고 API 응답에도 포함되지만, 일시 중지된 사용자에게는 보이지 않습니다.

일시 중지를 해제하려면 다음을 실행하세요.

curl -s -X POST "https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}:resume-login" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: resume-{MAILBOX_ID}"

상태 읽기

GET /api/v1/mailboxes/{id}와 목록 endpoint 모두 이 상태를 제공하므로, 아무것도 변경하지 않고 감사할 수 있습니다.

{ "data": { "id": 1701, "email": "sam@example.com", "status": "active",
            "login_suspended": true,
            "login_suspended_at": "2026-08-16T14:02:11+00:00",
            "login_suspended_reason": "Unpaid invoice 42", "...": "..." } }

status는 계속 active로 유지됩니다. 우회해야 할 오류가 아닙니다. 메일함은 활성 상태이며 메일을 받고 있습니다. 로그인 상태는 login_suspended에서, 메일함 자체의 작동 여부는 status에서 확인하세요.

여러 메일함을 한 번에 처리하기

curl -s -X POST "https://trekmail.net/api/v1/mailboxes:login-access" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: suspend-domain-123-august" \
  -d '{"domain_id":123,"login_suspended":true,"reason":"Unpaid invoice 42"}'

선택자는 정확히 하나만 전달하세요.

응답에서 처리 결과를 확인할 수 있습니다.

{ "data": { "login_suspended": true, "matched": 24, "updated": 21, "skipped": 3 } }

matched는 선택자가 찾은 메일함 수, updated는 실제로 변경된 수, skipped는 호출을 적용하지 못한 수입니다. 이미 요청한 상태인 메일함은 일치 항목으로 집계되지만 업데이트되지는 않습니다. 따라서 결제 작업에서 매일 밤 실행하는 경우처럼 호출을 안전하게 반복할 수 있습니다.

같은 대상의 접근을 복원하려면 "login_suspended": false를 설정하세요.

MCP 에이전트 사용하기

suspend_mailbox_login(mailbox_id=1701, reason="Unpaid invoice 42")
resume_mailbox_login(mailbox_id=1701)
set_mailboxes_login_access(domain_id=123, login_suspended=true, reason="Unpaid invoice 42")

필요한 범위를 가진 에이전트는 세 도구를 모두 사용할 수 있습니다. 로컬에 호스팅된 MCP 서버의 관리자는 쓰기 작업에 명시적 승인을 요구할 수 있습니다. 이를 통해 에이전트가 실수로 사용자의 접근을 차단하는 일을 방지할 수 있습니다.

로그인이 일시 중지된 메일함의 동작

일시 중지는 인터페이스에서만 숨겨지는 것이 아니라 모든 접근 지점에서 적용됩니다.

• 웹메일 로그인이 거부되고 이미 열려 있는 모든 세션이 종료됩니다
• IMAP, POP 및 SMTP 인증이 거부되므로 메일 앱이 작동을 멈추고 아무것도 보낼 수 없습니다
• CalDAV와 CardDAV가 거부되므로 캘린더와 연락처가 휴대전화 및 노트북과 동기화되지 않습니다
• 메일함의 메시지 토큰 (tm_msg_)은 422 mailbox_login_suspended로 응답합니다. 토큰은 취소되지 않으므로 로그인이 복원되면 다시 작동합니다
• 파일 동기화용 기기 비밀번호는 취소되며 이 조치는 영구적입니다. 일시 중지를 해제한 뒤 새 비밀번호를 만듭니다
• 비밀번호 재설정 링크와 복구 코드는 작동을 멈추며 새로 발급할 수도 없습니다. 접근을 차단하는 원인이 비밀번호가 아니므로 비밀번호를 재설정해도 접근은 복원되지 않습니다
• 수신 메일은 평소처럼 배달되며, 전달 규칙과 필터도 계속 작동합니다

삭제되는 것은 없습니다. 모든 메시지, 연락처, 캘린더 항목 및 파일은 원래 위치에 남습니다. 메일함은 계속 요금제와 저장 공간에 포함되며 메일을 받아 둡니다.

로그인이 중지된 메일함으로 마이그레이션

로그인이 중지된 메일함으로는 마이그레이션을 시작할 수 없습니다. POST /api/v1/migrations는 422 mailbox_login_suspended로 응답합니다. 가져오기 도구는 복사한 메일을 배달하기 위해 로그인하므로 작업이 도중에 실패합니다. 로그인을 복원하고 마이그레이션을 실행한 다음, 여전히 필요하면 다시 일시 중지하세요.

공유 메일함

단일 endpoint는 공유 메일함을 422 mailbox_unavailable로 거부하고, 대량 endpoint는 공유 메일함을 건너뛰지만 개수에는 포함합니다. 누구도 공유 메일함에 직접 로그인하지 않습니다. 팀은 자신의 메일함에서 공유 메일함을 열기 때문에 해당 사용자의 메일함 로그인을 일시 중지하면 공유 메일함을 포함한 접근이 차단됩니다. 공유 행에 일시 중지를 저장하면 효과가 있는 것처럼 보이지만 실제로는 아무것도 바뀌지 않습니다.

발생할 수 있는 오류