Files

T

ttipo fa6799d9f7 docs: 9단계(보내기 취소 · 예약 발송 · 외부 이미지 · 인쇄 · 보낸 사람 차단) 계약과 디자인

보내기 취소 · 예약 발송(엔진이 제출을 붙잡는다 — FUTURERELEASE), 외부 이미지 중계, 인쇄, 보낸 사람 차단, 보내기 · 읽기 설정의 계약(2절)을 정하고,
확정한 캔버스 보드 넷(MailReadTools · MailPrint · MailSendLater · SettingsSendRead)을 둔다. 디자인 README 에 구현하며 정한 보완을 적었다.
리뷰(화면 한 번 · 서버 두 번)로 정한 것도 함께 적었다 — 붙잡힌 메일은 취소로만 보낸편지함을 떠난다(MAIL_015 — 모든 옮기기 · 지우기 길, 확인하지 못하면 닫힌 쪽),
발송은 늘 envelope 을 직접 준다(엔진이 받지 않는 주소를 not-found 로 빼고 다시 제출 — 전에는 말없이 빠졌다), 다시 취소해도 200,
이미지 중계의 동시 수(서버 16 · 직원 6 — 받는 수가 적은 직원부터), 차단 주소는 dot-atom 만 · 다시 POST 하면 꺼진 규칙을 켠다.
엔진 사실(2026-10-29): envelope 의 거절은 제출 전체 · 첫 주소 하나, 내보내는 사본에서 Bcc 를 뗀다(개발의 Mailpit 이 보이는 Bcc 줄은 Mailpit 이 붙인다), 제출 조회의 정렬 이름은 sentAt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-29 22:07:45 +09:00

173 KiB

Raw Blame History

인증·메일 API 계약 (1단계)

백엔드와 프론트엔드를 병렬로 만들기 위한 계약이다. 구현이 끝나면 Swagger(/api-docs)와 프론트 타입이 기준이며, 이 문서와 어긋나면 이 문서를 고친다. 바꿔야 할 일이 생기면 한쪽에서 조용히 바꾸지 말고 이 문서부터 고친 뒤 양쪽에 알린다.

공통 규칙은 그대로 따른다 — 표준 응답 래퍼(response-format), 에러 코드(error-codes), API 규약(api-design).

성공 { "success": true, "data": … } / 실패 { "success": false, "error": { "code", "message", "traceId" } }
날짜·시각은 ISO 8601 UTC 문자열, 목록은 { items, pageInfo }
이 단계에서 쓰는 에러 코드: AUTH_001 AUTH_002(클라이언트 전용) AUTH_003 AUTH_004 AUTH_005 VAL_001 RES_001 REQ_001 FILE_001 FILE_002 MAIL_001 MAIL_002 MAIL_003 MAIL_004 MAIL_005 MAIL_006 MAIL_007 MAIL_008 MAIL_009 MAIL_010 MAIL_011 MAIL_012 MAIL_013 MAIL_014 MAIL_015 CONTACT_001 CONTACT_002 SYS_001
적용 범위: 1단계는 웹(브라우저) 전용이다. 인증은 HttpOnly 쿠키뿐이고 토큰을 본문으로 주지 않는다. 모바일 앱(Flutter)의 인증 방식(토큰 발급·flutter_secure_storage)은 앱 착수 때 이 문서에 추가한다.
배포 형태: 화면과 API 는 같은 주소(origin)를 쓴다. 운영은 프론트 nginx 가 /api 를 백엔드로 넘기고, 개발은 vite 프록시가 넘긴다. 그래서 CORS 가 필요 없고 CSP connect-src 'self' 로 충분하다.
출처 검사(CSRF): 상태를 바꾸는 요청(POST·PATCH·PUT·DELETE)은 브라우저가 붙이는 Sec-Fetch-Site·Origin 을 검사한다. 다른 사이트에서 온 요청은 403 AUTH_003. 출처 정보가 아예 없는 요청(브라우저가 아닌 클라이언트)은 통과한다.
프록시가 직접 내는 오류: 프론트 nginx 가 백엔드에 닿기 전에 끝내는 요청도 표준 실패 형식으로 온다 — 본문 한도 초과 413 FILE_002, 백엔드 응답 없음 502·시간 초과 504 SYS_001. traceId 는 nginx 요청 ID 이고 message 는 비어 있을 수 있으니 클라이언트는 코드로 사전 문구를 쓴다.

1. 인증 (쿠키 기반 — 토큰은 응답 본문에 없다)

쿠키	내용	속성
`access_token`	액세스 JWT (`JWT_ACCESS_EXPIRES_IN`, 기본 1h)	HttpOnly · SameSite=Lax · Path=`/api` · 운영 Secure
`refresh_token`	리프레시 JWT (`JWT_REFRESH_EXPIRES_IN`, 기본 14d)	HttpOnly · SameSite=Strict · Path=`/api/auth` · 운영 Secure

직원 계정 = 메일 계정이다. 백엔드는 로그인할 때만 비밀번호를 메일 엔진(Stalwart)에 확인하고 저장하지 않는다.

`POST /api/auth/login`

// 요청
{ "email": "ara.kim@arasystem.it.kr", "password": "…" }
// 200 + Set-Cookie(access_token, refresh_token)
{ "email": "ara.kim@arasystem.it.kr", "name": "김아라" }

실패	코드
계정 없음 · 비밀번호 틀림 · 사내 도메인이 아닌 주소 · 메일 엔진 관리자 계정(웹메일 로그인 대상이 아니다) (구분하지 않는다)	401 `AUTH_004`
형식 오류	400 `VAL_001`
시도 과다 — 같은 IP 에서 1분에 실패 20회, 같은 주소로 15분에 실패 10회 (성공한 로그인은 세지 않는다 — 사무실처럼 여러 직원이 한 IP 를 쓰는 환경 때문). 이와 별도로 같은 IP 의 로그인 요청은 1분에 60회까지. "같은 IP" 는 IPv6 를 /64 단위로 묶는다(IPv4-mapped 주소는 IPv4 로). 사내 도메인이 아닌 주소는 IP 한도에만 센다. 비밀번호 변경(`PUT /api/auth/password`)의 지금 비밀번호 틀림도 같은 한도로 함께 센다	429 `REQ_001`
같은 주소의 로그인 · 비밀번호 변경이 아직 처리 중 (버튼을 두 번 누른 경우 등)	429 `REQ_001`
대량 공격으로 서버가 기억하는 시도 기록이 상한에 닿았고 밀어낼 수 있는 기록이 없음 — 새 IP·주소의 로그인 (잠금 기록을 지키려고 막는 쪽을 택한다)	429 `REQ_001`
메일 엔진 장애	503 `MAIL_001`

`GET /api/auth/me`

앱 시작 시 세션 복원용. 200 { "email", "name" } / 로그인 안 됨 401 AUTH_001.

`POST /api/auth/refresh`

리프레시 쿠키로 두 쿠키를 새로 발급한다(회전). 200 { "email", "name" }.

실패	응답	세션·쿠키
쿠키 없음·만료·끊긴 세션, 메일 엔진이 계정을 찾지 못함(대리 접근 401), 그 계정이 엔진 관리 권한을 얻음	401 `AUTH_001`	쿠키 삭제·세션 폐기
메일 엔진 장애, 게이트웨이의 대리 접근 권한 문제(엔진 403 — 설정 실수)	503 `MAIL_001`	유지 — 설정을 고치면 그대로 이어 쓴다
서버 쪽 드문 불일치(회전 충돌)	500 `SYS_001`	유지 — 같은 쿠키로 다시 시도할 수 있다

세션 규칙 (서버에 저장한다)

로그인하면 서버에 세션이 하나 생긴다. 리프레시 토큰은 1회용이다 — 갱신할 때마다 새 토큰을 주고 이전 토큰은 폐기한다.
이미 쓴 리프레시 토큰이 다시 오면 탈취로 보고 그 세션 전체를 끊는다 → 401 AUTH_001.
- 예외(유예): 회전 직후 30초 안에 바로 이전 토큰이 오면(탭 여러 개가 동시에 갱신한 경우) 세션을 끊지 않고 200 { "email", "name" } 으로 답하되 쿠키는 새로 주지 않는다 — 먼저 갱신한 요청이 받은 쿠키를 같이 쓴다. 두 번 이상 지난 토큰이나 30초가 지난 이전 토큰은 위 규칙대로 세션을 끊는다.
세션은 로그인 후 최대 30일(절대 만료)이다. 그 안에서도 리프레시 토큰을 14일 동안 쓰지 않으면 끝난다.
액세스 토큰은 서버 조회 없이 검증한다. 그래서 세션을 끊어도 이미 발급된 액세스 토큰은 만료(최대 1시간)까지 유효하다.

`POST /api/auth/logout`

항상 200 (data: null). 두 쿠키를 지우고 서버의 세션을 폐기한다.

`PUT /api/auth/password` — 4단계

// 요청 (로그인 필요)
{ "currentPassword": "…", "newPassword": "…" }
// 200 (data: null)

실패	코드
지금 비밀번호가 틀림	400 `AUTH_005` — 세션은 그대로다. 401 이 아닌 까닭: 클라이언트는 401 이면 세션을 갱신하고 같은 요청을 다시 보낸다
새 비밀번호가 8자 미만 · 128자 초과 · 지금 비밀번호와 같음, 엔진 규칙에 어긋남 · 지금 비밀번호가 비었거나 256자 초과(로그인과 같은 한도) — 길이는 JS 문자열 길이	400 `VAL_001`
지금 비밀번호 틀림이 잦음 — 로그인 실패와 같은 한도(같은 IP 1분 20회 · 같은 주소 15분 10회)를 함께 센다. 같은 주소의 로그인 · 변경이 처리 중	429 `REQ_001`
웹메일로 다루지 않는 계정(메일 엔진 관리자 · 게이트웨이 · 막은 계정 — 엔진에 묻지 않는다)	401 `AUTH_001`
메일 엔진 장애 — 바꾸는 요청의 결과를 알 수 없는 실패(시간 초과 · 연결 끊김 · 5xx)도	503 `MAIL_001` — 결과를 모를 때는 바뀌었을 수 있으므로 다른 세션을 끊어 둔다

서버는 메일 엔진에 그 직원 본인의 자격으로(지금 비밀번호) 본인 비밀번호 변경(Stalwart x:AccountPassword/set 에 currentSecret · secret)을 보낸다 — 게이트웨이 대리 접근이나 관리자 권한을 쓰지 않는다. 엔진은 지금 비밀번호 없이는 바꾸지 않고 8자 미만을 거절한다 (2026-10-28 개발 엔진에서 확인). 세션은 같은 값으로 열렸는데 엔진이 바꾸기를 거절하면(forbidden · currentSecret 의 invalidProperties · 바꾸기 요청의 401 — 앱 비밀번호를 넣은 경우 · 역할의 권한 설정) AUTH_005 로 답하되 실패 횟수로 세지 않고 세션도 끊지 않는다(추측이 아니라서). 결과를 알 수 없는 실패도 실패 횟수로 세지 않는다.
바뀌면 그 직원의 다른 로그인 세션을 모두 끊는다 — 이 요청의 리프레시 쿠키(Path=/api/auth 라 이 요청에도 온다)가 가리키는 세션만 남긴다. 쿠키가 없거나 다른 직원 것이면 이 세션도 끊긴다(다음 갱신에서 로그인 화면으로). 끊긴 기기의 액세스 토큰은 만료(최대 1시간)까지 쓰인다(위 세션 규칙). 휴대폰 · PC 메일 프로그램(IMAP)은 새 비밀번호를 다시 넣어야 한다.
비밀번호는 바뀌었는데 세션 끊기가 실패하면 200 으로 답하고 오류 로그를 남긴다 — 실패로 답하면 사용자가 옛 비밀번호로 다시 시도하기 때문이다.
비밀번호는 로그 · 응답에 남기지 않는다. 바꾼 일은 info 로그에 주소(가린 것)만 남긴다.
클라이언트: 같은 규칙(8자 이상 · 지금과 다름 · 확인 칸 일치)을 먼저 보고, AUTH_005 는 지금 비밀번호 칸 아래에 사전 문구로 보인다. 성공하면 세 칸을 비운다. 요청 한도는 30초다 — 서버가 엔진을 두 번 부르고 세션을 끊으므로, 기본 한도(10초)로는 서버가 바꾼 뒤 화면만 실패로 볼 수 있다.

클라이언트 처리 규칙

보호 API 가 401 AUTH_001 을 주면 한 번만 /auth/refresh 를 시도하고, 성공하면 원래 요청을 다시 보낸다. 실패하면 기존 규칙대로 AUTH_002 로 승격하고 로그인 화면으로 보낸다. /auth/login · /auth/refresh · /auth/me · /auth/logout 은 이 재시도 대상이 아니다.
/auth/refresh 의 200 은 Set-Cookie 가 없어도 성공으로 다룬다 (위 유예 응답).
세션이 끝난 것은 /auth/refresh 의 401 AUTH_001 뿐이다. 5xx(MAIL_001·SYS_001)·네트워크 오류는 일시 장애로 알리고 로그아웃으로 다루지 않는다.
로그인 버튼은 응답이 올 때까지 다시 누를 수 없게 한다 — 같은 주소로 동시에 보낸 두 번째 요청은 429 REQ_001 이다.
로그아웃하면 같은 브라우저의 다른 탭에도 알린다(BroadcastChannel). 알림을 받은 탭은 로그인 화면으로 간다.
로그아웃(어느 탭에서든) 뒤에 도착한 /auth/refresh 성공은 쓰지 않고 /auth/logout 을 한 번 더 부른다. 갱신과 로그아웃이 겹치면 서버가 로그아웃 뒤에 새 쿠키를 구울 수 있기 때문이다 (세션은 끊겼어도 액세스 토큰은 만료까지 유효).
앱 시작 시 /auth/me 로 세션을 복원한다. 이 호출의 AUTH_001 은 로그인 전 정상 상태이므로 알림을 띄우지 않는다.
복원 중 /auth/me 가 AUTH_001 이면 액세스 토큰만 만료됐을 수 있으므로 /auth/refresh 를 알림 없이 한 번 부르고, 성공하면 복원 완료, 실패하면 로그아웃 상태로 시작한다. → 백엔드는 액세스 쿠키가 없거나 만료돼도 리프레시 쿠키만으로 /auth/refresh 가 동작해야 한다.

2. 메일 (모두 로그인 필요 — 없으면 401 `AUTH_001`)

타입

interface Address { name: string | null; email: string }

interface Mailbox {
  id: string
  name: string            // 역할이 있으면 한국어 표준 이름, 없으면 서버의 이름
  role: 'inbox' | 'drafts' | 'sent' | 'junk' | 'trash' | 'archive' | null
  parentId: string | null
  sortOrder: number
  totalCount: number
  unreadCount: number
}

interface MessageSummary {
  id: string
  threadId: string
  mailboxIds: string[]
  from: Address | null
  to: Address[]
  subject: string         // 제목이 없으면 빈 문자열
  preview: string
  receivedAt: string
  isRead: boolean
  isFlagged: boolean
  hasAttachment: boolean  // 본문 그림(아래)만 있으면 false — 서명 그림만 붙은 메일은 첨부 표시를 하지 않는다
  size: number            // 바이트
  pendingSend: PendingSend | null  // 아직 보내지 않은 내 메일(보내기 취소를 기다리는 중 · 예약)이면 그 정보 — 9단계 "보내기 취소 · 예약 발송". 그 밖에는 null
}

interface MessageDetail extends MessageSummary {
  cc: Address[]
  bcc: Address[]
  replyTo: Address[]
  sentAt: string | null
  messageId: string | null    // Message-ID 헤더 (답장 스레드 연결용)
  references: string[]
  htmlBody: string | null     // 서버가 정화한 HTML (아래 참고)
  textBody: string | null
  hasBlockedImages: boolean   // 외부 이미지를 지웠으면 true → "외부 이미지 차단" 안내 (보이게 했으면 false)
  imagesShown: boolean        // 외부 이미지를 중계 주소로 바꿔 넣었으면 true — 9단계 "외부 이미지 보기" (`images=show` 또는 설정)
  isHtmlBodyOmitted: boolean  // HTML 이 있었지만 정화 한도를 넘어 htmlBody 를 비웠으면 true (아래 "읽기 한도")
  isBodyTruncated: boolean    // 보여 줄 본문(htmlBody — null 이거나 공백뿐이면 textBody)이 읽기 한도에서 잘렸으면 true
  attachments: MessageAttachment[]
}

interface Attachment { id: string; name: string; type: string; size: number }

interface MessageAttachment extends Attachment {
  isInline: boolean           // 돌려준 htmlBody 안에 그림으로 들어갔다(cid → data:) — 읽기 화면의 첨부 목록에서 뺀다. 전달할 때는 함께 붙인다
}

역할별 한국어 이름: inbox 받은편지함 · drafts 임시보관함 · sent 보낸편지함 · junk 스팸메일함 · trash 휴지통 · archive 보관함.

htmlBody 정화 규칙 (서버 책임): 스크립트·스타일 태그·이벤트 핸들러·폼·iframe·object·embed·svg 제거, 링크는 http · https · mailto 만 남기고 새 창(target="_blank" rel="noopener noreferrer"), 외부(http/https) 이미지는 제거하고 hasBlockedImages = true (보이게 할 때는 중계 주소로 바꾼다 — 아래 "외부 이미지 보기", 9단계). 본문 안 인라인 이미지(cid:)는 작은 것만 data: URI 로 바꿔 넣고 나머지는 지운다. 넣은 그림은 attachments 에 isInline: true 로 남는다 — 읽기 화면은 첨부 목록에서 빼고, 전달은 원문 그림을 잃지 않게 함께 붙인다 (인용 본문에서는 그림이 빠지기 때문이다). 넣지 못한 그림(크거나 많거나 읽지 못함)은 isInline: false 로 첨부 목록에 보인다. 클라이언트는 그래도 격리된 iframe 에만 그린다 (스크립트 비허용 sandbox + 내부 CSP — 이중 방어).

hasAttachment 는 엔진 값이 아니라 서버가 첨부 부분의 머리로 정한다 — "본문 그림"이 아닌 첨부가 하나라도 있으면 true. 본문 그림 = 본문에 넣을 수 있는 그림 형식(PNG·JPEG·GIF·WebP) · Content-ID 있음 · Content-Disposition 이 attachment 가 아님(inline 이거나 없음) · 크기 1바이트~300KB. 목록은 본문을 읽지 않으므로 이 판정은 "실제로 본문에 들어갔나"(isInline)와 드물게 다를 수 있다 (본문이 가리키지 않는 그런 그림, 20장·합계 2MB 를 넘는 본문 그림 — 목록은 클립이 없는데 상세의 첨부 목록에는 보인다).

읽기 한도: 상세 조회는 본문 한 부분을 UTF-8 2,000,000바이트까지 읽는다 — 넘는 부분은 잘린 채 오고, 보여 줄 본문이 잘렸으면 isBodyTruncated: true 다. HTML 은 정화하기 전에 길이(HTML 부분이 여럿이면 이어 붙인 것이 2,000,000자 이하)와 파서 비용을 본다 — 약 2만 단을 넘는 중첩이나, 깊게 열린 태그 아래로 짝 없는 닫는 태그를 아주 많이 둔 HTML 은 정화가 서버를 수십 초씩 붙잡기 때문이다. 넘으면 정화하지 않고 htmlBody: null·hasBlockedImages: false·isHtmlBodyOmitted: true 로 내려준다. textBody 는 그대로라 클라이언트는 그것을 보여 주고 답장·전달 인용도 그것으로 만든다 (HTML 만 있는 메일이면 둘 다 null). 수백 단의 인용 스레드·2MB 짜리 큰 표·Outlook 조건부 주석은 한도 안이다. 클라이언트는 두 표시를 읽기 화면에 알리고(서식 없이 표시 · 표시할 수 없음 · 앞부분만 표시), 잘린 본문을 인용할 때는 인용 끝에 생략 표시를 둔다.

엔드포인트

메서드 · 경로	요청	성공	주요 실패
`GET /api/mailboxes`	—	200 `{ items: Mailbox[], pageInfo }` (hasNext=false)	`MAIL_001`
`POST /api/mailboxes`	`{ name, parentId? }` (아래 "메일함 관리")	201 `Mailbox`	400 `VAL_001`, 404 `RES_001`(없는 parentId), 409 `MAIL_009`(같은 자리에 같은 이름), 503 `MAIL_001`
`PATCH /api/mailboxes/{id}`	`{ name }`	200 `Mailbox`	400 `VAL_001`(기본 메일함), 404 `RES_001`, 409 `MAIL_009`, 503 `MAIL_001`
`DELETE /api/mailboxes/{id}`	—	200 `MailboxDeletion` — 안의 메일을 휴지통으로 옮긴 뒤 지운다	400 `VAL_001`(기본 메일함 · 하위 메일함 있음), 404 `RES_001`, 409 `MAIL_015`(남은 메일이 붙잡힌 메일뿐 — 9단계 "보내기 취소 · 예약 발송"), 429 `REQ_001`(같은 메일함의 처리가 진행 중), 503 `MAIL_001`
`PATCH /api/mailboxes/{id}/messages`	`{ isRead: true }` — 그 메일함 전체를 읽음으로	200 `MailboxBulkResult`	400 `VAL_001`, 404 `RES_001`, 429 `REQ_001`(같은 메일함의 처리가 진행 중), 503 `MAIL_001`
`DELETE /api/mailboxes/{id}/messages`	— 휴지통 · 스팸메일함 비우기(영구 삭제)	200 `MailboxBulkResult`	400 `VAL_001`(휴지통 · 스팸메일함이 아님), 404 `RES_001`, 409 `MAIL_015`(남은 메일이 붙잡힌 메일뿐 — 9단계), 429 `REQ_001`(같은 메일함의 처리가 진행 중), 503 `MAIL_001`
`GET /api/mail-vacation`	—	200 `MailVacationState` (아래 "부재중 자동 응답" — `MailVacation` + 7단계의 `isActive`)	503 `MAIL_001`
`PUT /api/mail-vacation`	`MailVacation` (전체 교체 — `isActive` 는 보내지 않는다)	200 `MailVacationState`(저장한 값)	400 `VAL_001` · `MAIL_013`(필터와 함께 만든 엔진 규칙이 한도를 넘음 — 6단계), 503 `MAIL_001`
`GET /api/mail-filters`	—	200 `MailFilterSet` (아래 "메일 필터", 6단계)	503 `MAIL_001`
`PUT /api/mail-filters`	`{ rules, version }` (전체 교체)	200 `MailFilterSet`	400 `VAL_001` · `MAIL_013`(만든 규칙이 엔진 한도를 넘음), 409 `MAIL_012`(그사이 다른 곳에서 필터가 바뀜 — 저장 안 함), 503 `MAIL_001`
`POST /api/mail-filter-runs`	`MailFilterRunRequest` — 받은편지함에 이미 있는 메일에 규칙 하나를 적용한다(아래 "이미 받은 메일에 적용", 7단계)	200 `MailFilterRun` — 붙잡힌 메일(9단계)은 옮기지 않고 표시만	400 `VAL_001`(규칙 검사 · 할 일 없음 · 깨진 cursor), 429 `REQ_001`(같은 직원의 적용이 진행 중), 503 `MAIL_001`
`GET /api/mail-quota`	—	200 `MailQuota`	`MAIL_001`
`GET /api/mail-state`	—	200 `MailState` (아래 "새 메일 확인")	503 `MAIL_001`
`GET /api/mail-events`	—	`text/event-stream` (표준 래퍼 없음 — 아래 "실시간 알림", 5단계)	401 `AUTH_001`, 429 `REQ_001`(한 직원의 연결 5개 초과), 503 `MAIL_001`
`GET /api/messages`	`mailboxId` · `cursor` · `limit`(기본 20, 최대 100) · `q` — `mailboxId` 와 `q` 중 하나는 있어야 한다(`q` 만 있으면 휴지통·스팸메일함을 뺀 모든 메일함에서 찾는다 — 아래 "검색")	200 `{ items: MessageSummary[], pageInfo }` — 받은 시각 내림차순, `total` 포함	400 `VAL_001`, `MAIL_001`
`GET /api/messages/{id}`	`images`(선택 — `show` 면 외부 이미지를 보이는 본문, 9단계 "외부 이미지 보기")	200 `MessageDetail` — 조회만으로 읽음 처리하지 않는다	400 `VAL_001`(모르는 `images` · 모르는 쿼리 — 9단계부터, 전에는 무시했다), 404 `RES_001`
`PATCH /api/messages/{id}`	`{ isRead?, isFlagged?, mailboxId?, isJunk? }` (하나 이상 — `isJunk` 는 4단계 "스팸 · 원문")	200 `MessageSummary`	404 `RES_001`, 400 `VAL_001`, 409 `MAIL_015`(붙잡힌 메일의 `mailboxId` · `isJunk` — 9단계, 아래 "보내기 취소 · 예약 발송"), 503 `MAIL_001`(붙잡혔는지 확인하지 못함 — 바꾸지 않았다)
`PATCH /api/messages`	`{ ids, isRead?, isFlagged?, mailboxId?, isJunk? }` — 여러 통 (아래 "여러 통 한꺼번에")	200 `MessagesPatched` — 붙잡힌 메일(9단계)의 `mailboxId` · `isJunk` 는 바꾸지 않고 `failedIds` 로	400 `VAL_001`, 404 `RES_001`(없는 `mailboxId` — 아무것도 바꾸지 않음), 503 `MAIL_001`
`DELETE /api/messages/{id}`	—	204 — 휴지통이 아니면 휴지통으로 이동, 휴지통에만 있으면 영구 삭제(확인한 상태 그대로일 때만 — 아래). 휴지통과 다른 메일함에 함께 있으면 휴지통에서만 뺀다. 웹 클라이언트는 쓰지 않는다(3단계 — 아래 "여러 통 한꺼번에")	404 `RES_001`, 409 `MAIL_015`(붙잡힌 메일 — 9단계), 503 `MAIL_001`(확인하는 사이 계속 바뀜 — 지우지 않았다)
`POST /api/message-deletions`	`{ ids }` — 휴지통에서 영구 삭제, 여러 통 (아래 "여러 통 한꺼번에") — 붙잡힌 메일(9단계)은 건너뛴다(`skippedIds`)	200 `MessageDeletionResult`	400 `VAL_001`, 503 `MAIL_001`(확인하는 사이 계속 바뀜 · 휴지통 없음 — 지우지 않았다)
`POST /api/messages`	아래 발송 본문 + `Idempotency-Key` 헤더 (예약은 `sendAt` — 9단계)	201 `SentMessage` (보낸편지함의 메일 id + 받지 못한 사람 — 아래 "받는 사람별 결과" + 붙잡아 둔 발송 `pendingSend` — 9단계)	400 `MAIL_002`·`MAIL_003`·`MAIL_004`·`MAIL_006`·`MAIL_007`·`MAIL_010`(받는 사람 모두 거절 — 없는 주소 등)·`VAL_001`, 403 `AUTH_003`(보낼 권한 없음), 409 `MAIL_005`(같은 키·다른 내용), 413 `FILE_002`(첨부 합계 초과 포함), 429 `REQ_001`(엔진 발송 한도·같은 키 처리 중·엔진 장애 직후 30초), 503 `MAIL_001` · `MAIL_011`(받는 사람 모두 지금은 받을 수 없음)
`POST /api/mail-attachments`	multipart `file` 1개	201 `Attachment`	400 `FILE_001`, 413 `FILE_002`
`GET /api/messages/{id}/attachments/{attachmentId}`	—	파일 (표준 래퍼 없음, `Content-Disposition: attachment`)	404 `RES_001`
`GET /api/messages/{id}/source`	—	받은 그대로의 메일 `message/rfc822` (표준 래퍼 없음, `Content-Disposition: attachment; filename="<제목>.eml"`) — 4단계	404 `RES_001`, 503 `MAIL_001`
`GET /api/drafts/{id}`	—	200 `Draft` (아래 "임시 저장")	404 `RES_001`(없음·초안이 아님), 503 `MAIL_001`
`POST /api/drafts`	초안 본문	201 `DraftSaved`	400 `VAL_001`·`MAIL_002`·`MAIL_003`·`MAIL_004`·`MAIL_006`·`MAIL_007`·`FILE_001`, 413 `FILE_002`, 503 `MAIL_001`
`PUT /api/drafts/{id}`	초안 본문 (전체 교체)	200 `DraftSaved` — 새 id	위와 같음 + 404 `RES_001`(초안이 아닌 id — 지우지 않음) + 409 `MAIL_008`(다른 곳에서 이미 바뀜 — 저장 안 함)
`GET /api/mail-signature`	—	200 `MailSignature` (아래 "서명")	—
`PUT /api/mail-signature`	`{ bodyHtml, body, isForNew, isForReply }`	200 `MailSignature`	400 `VAL_001`
`POST /api/mail-signature/images`	multipart `file` 1개	201 `SignatureImage`	400 `FILE_001`·`VAL_001`(올려 둔 그림 10장 초과), 413 `FILE_002`(300KB 초과)
`GET /api/mail-signature/images/{id}`	—	그림 파일 (표준 래퍼 없음, 본인 그림만)	404 `RES_001`
`GET /api/recipient-suggestions`	`q`(선택, 1~100자) · `limit`(기본 20, 최대 100) · `cursor`	200 `{ items: RecipientSuggestion[], pageInfo }` (아래 "받는 사람 추천")	400 `VAL_001`, 503 `MAIL_001`
`GET /api/scheduled-messages`	`cursor` · `limit`(기본 20, 최대 100)	200 `{ items: MessageSummary[], pageInfo }` — 예약한 메일, 보낼 시각 차례, `total` 포함 (아래 "보내기 취소 · 예약 발송", 9단계)	400 `VAL_001`, 503 `MAIL_001`
`DELETE /api/scheduled-messages/{id}`	— (`id` 는 보낸 사본의 메일 id)	200 `{ draftId }` — 붙잡은 발송을 취소하고 임시보관함으로(보내기 취소 · 예약 취소). 이미 취소한 발송이면 다시 200(같은 id)	404 `RES_001`(형식이 틀린 id 포함), 409 `MAIL_014`(이미 보냄 · 기다리는 발송이 아님), 503 `MAIL_001`
`GET /api/mail-images/{token}`	—	바깥 이미지 (표준 래퍼 없음 — 아래 "외부 이미지 보기", 9단계)	404 `RES_001`(까닭을 가리지 않는다)
`GET /api/mail-settings`	—	200 `MailSettings` (아래 "보내기 · 읽기 설정", 9단계)	—
`PATCH /api/mail-settings`	`Partial<MailSettings>` — 하나 이상	200 `MailSettings`	400 `VAL_001`
`GET /api/mail-blocks`	—	200 `MailBlockList` (아래 "보낸 사람 차단", 9단계)	503 `MAIL_001`
`POST /api/mail-blocks`	`{ address }` — 주소 또는 `@도메인`	201 `BlockedSender` (이미 있으면 200 — 꺼져 있던 규칙도 켠다)	400 `VAL_001` · `MAIL_013`, 503 `MAIL_001`
`DELETE /api/mail-blocks/{address}`	— (URL 인코딩)	200 `{ address }`	404 `RES_001`(차단하지 않은 주소 · 틀린 모양), 503 `MAIL_001`

표에 없는 실패 (구현에서 확정):

상황	응답
없는 `mailboxId`, 엔진이 해석하지 못하는 `mailboxId`	404 `RES_001`
엔진이 해석하지 못하는 id — 여러 통 처리의 `ids`(`PATCH /api/messages` · `POST /api/message-deletions`), 메일함 없이 하는 검색	400 `VAL_001` (본문에서 온 값이라서 — 메일함 하나의 목록은 위처럼 404 `RES_001`)
형식이 틀린 경로 id	404 `RES_001`
받는 사람 합계 100명 초과 (배열 하나가 100을 넘으면 `VAL_001`)	400 `MAIL_002`
엔진에서 찾을 수 없는 첨부 id — 올려 두고 오래 지나 만료된 업로드, 그사이 지워진 원본 메일의 첨부 등	400 `MAIL_004` — 클라이언트는 해당 첨부를 실패로 표시한다. 올린 파일은 다시 올리게, 전달하는 원본 첨부는 빼게 한다 (원본은 다시 올릴 수 없다)
첨부 20개 초과	400 `MAIL_006` — 클라이언트는 첨부를 추가할 때 미리 막는다
본문이 너무 김 — 텍스트 100,000자·서식 본문 500,000자 초과(JS 문자열 길이, UTF-16 단위), 서식 본문이 정화 전 비용 한도·정화 뒤 2,000,000바이트 초과	400 `MAIL_007` — 메일은 나가지 않는다. 클라이언트는 보내기 전에 같은 한도로 막고 본문 아래에 알린다 (아래 "서식 본문"의 한도)
JSON 본문 1MB 초과 (발송 `POST /api/messages` 와 임시 저장 `POST /api/drafts`·`PUT /api/drafts/{id}` 만 4MB — 서식 본문과 긴 인용 때문)	413 `FILE_002`
JSON 본문의 모양이 한도를 넘음 — 배열 하나 1,000개 · 값(객체 · 배열 · 원시 값) 10,000개 · 깊이 32단	400 `VAL_001`
JSON 본문이 UTF-8 이 아님 — `charset` 이 `utf-16` · `utf-32` · `utf-7` 등 (`charset` 을 붙이지 않거나 `utf-8` 이면 된다)	400 `VAL_001`

JSON 본문 모양 한도 (2026-10-28 — 6단계 리뷰에서, 전부터 있던 경로도 같은 원인): 본문 크기 한도 안에서도 작은 객체 수만~수십만 개면 DTO 변환 · 검사가 몇 초씩 서버를 멈추고 수백 MB 를 썼다 (리뷰 측정 — 1MB 에 필터 규칙 8만 개 7.8초, 조건 15만 개는 500). 그래서 모든 JSON 본문을 DTO 에 닿기 전에 본다 — 읽기 전에 글자를 한 번 훑고, 읽은 뒤 한 번 더. 한도는 지금 계약의 어떤 본문보다 넉넉하다(가장 긴 배열 100 · 가장 깊은 본문 5단 · 값이 가장 많은 필터 50개 저장이 약 1,600개). 이 검사와 UTF-8 검사는 본문 크기 한도처럼 인증보다 앞이라, 로그인하지 않은 요청도 401 이 아니라 400 이다. JSON 은 UTF-8 만 받는다(RFC 8259 8.1 — 웹 · 앱 모두 UTF-8 로 보낸다).

메일함 정렬(확정 디자인 기준): 받은편지함 → 보낸편지함 → 임시보관함 → 스팸메일함 → 휴지통 → 보관함 → 그 외(sortOrder, 이름 순).

// GET /api/mail-quota — 메일함 패널 하단 사용량 표시와 첨부 사전 검사에 쓴다
interface MailQuota {
  usedBytes: number
  limitBytes: number | null    // 한도가 없으면 null → "사용량 0.9GB" 처럼 사용량만 표시
  attachmentMaxBytes: number   // 서버의 MAIL_ATTACHMENT_MAX_SIZE_MB — 클라이언트는 상수 대신 이 값으로 사전 검사·안내한다
  attachmentTotalMaxBytes: number // 메일 한 통의 첨부 합계 한도 — MAIL_ATTACHMENT_TOTAL_MAX_SIZE_MB 와 엔진 한도 중 작은 값 (발송 때 검사하는 값과 같다)
}

cursor 는 불투명 문자열이다. 클라이언트는 해석하지 말고 pageInfo.nextCursor 를 그대로 다시 보낸다.

발송 본문 (`POST /api/messages`)

중복 발송 방지 — Idempotency-Key 요청 헤더: 클라이언트는 쓰기 화면마다 무작위 키(UUID) 하나를 만들어 보내고, 같은 메일을 다시 보낼 때(타임아웃 뒤 재시도 등)에도 같은 키를 보낸다. 서버는 같은 사용자·같은 키로 이미 발송된 메일이 있으면 다시 보내지 않고 그 결과(201 SentMessage — 아래 "받는 사람별 결과")를 돌려준다. 응답이 늦어 MAIL_001 을 받았어도 실제로는 나갔을 수 있으므로, 재시도는 반드시 같은 키로 한다. (키 형식이 틀리면 400 VAL_001. 키가 없으면 중복 방지 없이 보낸다.) 서버는 발송 요청에 55초 안에 답한다 — 앞 단계(첨부 확인 · 서명 그림 올리기)가 늦어 보낼 시간이 10초도 남지 않으면 메일을 만들지 않고 503 MAIL_001 (아무것도 나가지 않았으니 같은 키로 다시 보내면 된다). 보낸 뒤 이어 쓴 저장본 지우기는 5초까지만 기다리고, 넘으면 먼저 답한 뒤 마저 지운다.

같은 키의 요청이 아직 처리 중이면 기다리지 않고 429 REQ_001 — 같은 메일이 동시에 두 번 나가지 않게 한다. 엔진 장애(MAIL_001)로 끝난 키도 30초 동안은 처리 중으로 본다 (시간 초과라면 엔진이 아직 보내는 중일 수 있다). 클라이언트는 이 429 에 같은 키로 즉시 자동 재시도하지 않고, 잠시 뒤 사용자가 다시 보내게 한다(키는 그대로).
같은 키인데 내용이 다르면(실패 뒤 받는 사람·제목·본문·첨부를 고친 경우) 보내지 않고 409 MAIL_005. 첫 메일이 실제로 나갔을 수 있으므로, 클라이언트는 사용자에게 보낸편지함을 확인하게 하고 새 키로 다시 보낼 수 있게 한다. 서버는 첫 발송 때 내용 지문(Idempotency-Key 를 키로 한 HMAC — 받는 사람은 키를 모른다)을 함께 남겨 비교한다.
- 지문에 들어가는 것: 받는 사람·참조·숨은참조의 주소(대소문자·순서 무시), 제목, 본문(줄바꿈 정규화), 서식 본문(서버가 정화한 HTML), 첨부 id(순서 무시), inReplyTo.
- 들어가지 않는 것: 표시 이름, 첨부 이름 — 이것만 바꾼 재시도는 "같은 내용"으로 보고 처음 결과를 돌려준다.
알려진 한계 (1단계는 발송 기록을 따로 저장하지 않고 보낸편지함에서 찾는다):
- 첫 발송 뒤 보낸 사본을 다른 메일함으로 옮기거나 지웠으면, 또는 그사이 보낸편지함·임시보관함에 200통 넘게 쌓였으면 같은 키의 재시도가 다시 나갈 수 있다.
- "처리 중" 표시는 서버 메모리에 있어 서버가 재시작되면 사라진다. 엔진 장애 직후의 드문 경합에서도 두 번 나갈 수 있다.
- 서식 본문의 지문은 정화한 결과로 만든다 — 첫 발송과 재시도 사이에 서버의 정화 규칙이 바뀌면(배포) 같은 키의 재시도가 MAIL_005 로 막힐 수 있다. 그때도 위 409 처리(보낸편지함 확인 → 새 키)를 따른다.
- 이 한계를 없애려면 (사용자, 키) → (지문, 메일 id) 를 서버 DB 에 저장한다 — 서버를 여러 대로 늘릴 때 함께 검토한다.

{
  "to":  [{ "name": "이도윤", "email": "doyun.lee@arasystem.it.kr" }],  // 1개 이상
  "cc":  [],                                                              // 선택
  "bcc": [],                                                              // 선택 (받는 사람 합계 100 이하)
  "subject": "Re: 메일 서버 이전 일정 공유",                               // 255자 이하
  "body": "도윤님, 확인했습니다.\n…",                                       // 일반 텍스트(서식 본문의 대체 본문), 100,000자 이하
  "bodyHtml": "<div style=\"font-family:…\"><p>도윤님, 확인했습니다.</p>…</div>", // 선택 — 서식 편집기 본문, 500,000자 이하 (아래 "서식 본문")
  "attachments": [{ "id": "<업로드 응답 id>", "name": "체크리스트.xlsx" }], // 선택, 20개 이하 (넘으면 MAIL_006)
  "inReplyTo": "<답장할 메일의 id>",                                       // 선택 — 스레드 헤더를 서버가 채운다
  "draftId": "<이어 쓴 임시 저장본 id>",                                     // 선택 — 보낸 뒤 서버가 그 초안을 지운다 (아래 "임시 저장")
  "sendAt": "2026-10-30T00:00:00.000Z"                                       // 선택 — 예약 발송: 지금부터 5분 뒤 ~ 7일 안 (9단계 "보내기 취소 · 예약 발송")
}

받는 사람별 결과 (발송 응답) — 6단계 앞 수정

interface SentMessage {
  id: string                                  // 보낸편지함의 메일 id
  rejectedRecipients: RejectedRecipient[]     // 엔진이 받지 않은 사람 — 없으면 빈 배열
  pendingSend: PendingSend | null             // 엔진이 붙잡아 둔 발송이면 그 정보(보내기 취소 · 예약 — 9단계), 바로 보냈으면 null
}
interface RejectedRecipient {
  email: string                               // 요청에 쓴 주소 그대로 (받는 사람 · 참조 · 숨은참조 모두 — 같은 주소는 한 번)
  reason: 'not-found' | 'refused' | 'temporary'  // 없는 주소 · 받는 쪽이 거절 · 지금은 받을 수 없음(한도 등)
}

엔진은 제출(EmailSubmission/set)을 만들면서 받는 사람마다 그 자리에서 SMTP 로 묻는다. 거절된 사람은 제출 기록의 deliveryStatus 에 delivered: "no" 와 SMTP 응답(550 5.1.2 Mailbox does not exist · 452 4.4.5 Rate limit exceeded 등)으로만 남고 다시 보내지도 반송하지도 않는다 (Stalwart 0.16.27 — 2026-10-28 확인. 전에는 서버가 이것을 보지 않아, 없는 사내 주소로 보낸 메일도 "보냈습니다"로 끝났다). 그래서 서버가 제출한 뒤 결과를 읽어 알린다.
- 결과는 제출 다음 따로 읽는다(EmailSubmission/get) — 제출 응답(created)에는 없고, 같은 요청 안의 참조(#ids)는 onSuccessUpdateEmail 이 덧붙이는 응답 때문에 엔진이 풀지 못한다(같은 날 확인).
- 분류 — SMTP 응답 맨 앞의 기본 코드(550)와 확장 상태(5.1.2)만 읽는다(응답 글 안의 숫자는 보지 않는다). 4xx 면 temporary, 5xx 이고 확장 상태가 5.1.x(받는 사람 주소 문제)면 not-found, 그 밖의 5xx 와 읽을 수 없는 응답은 refused — 두 값이 어긋나면 기본 코드를 따른다(450 5.1.1 은 temporary). 5.1.7 · 5.1.8(보낸 사람 주소 문제)도 not-found 로 보이는데, 엔진의 제출 때 거절에는 나오지 않고 같은 키 재시도가 바깥 반송까지 읽을 때만 생길 수 있다. delivered 가 "no" 가 아니거나 결과가 없는 사람은 받은 것으로 본다 — 바깥 주소는 대기열에 들어가 250 Queued 이고, 나중에 실패하면 지금처럼 반송 메일이 온다.
- 결과를 읽지 못하면(엔진 오류 · 시간) 보낸 것으로 보고 rejectedRecipients: [] 로 답한다(warn 로그) — 제출은 이미 되었다. 결과 읽기는 발송 전체 55초 안에서 최대 5초(모두 거절일 때 사본을 지울 3초를 남긴다), 쓸 시간이 1초도 안 남으면 묻지 않는다.
- 같은 주소(대소문자 무시)는 한 번만 싣는다 — 받는 사람 → 참조 → 숨은참조 순서이고 처음 쓴 모양 그대로.
엔진이 받지 않는 주소(9단계 리뷰 뒤 — 2026-10-29 실엔진): 발송은 늘 envelope(받는 사람 · 참조 · 숨은참조, 같은 주소는 하나)을 직접 준다. 엔진은 envelope 에 받지 않는 주소(모르는 최상위 도메인 x@example.cmo · 따옴표 앞부분 "a b"@… 등)가 있으면 제출 전체를 거절하고 그 가운데 첫 주소 하나만 알려 준다. 서버는 그 주소를 not-found 로 빼고 같은 메일을 나머지에게 다시 제출한다 — 붙잡기(9단계)는 그대로이고, 차례마다 하나씩 뺀다. 거절 글이 따옴표로 싼 주소와 정확히 같은 받는 사람부터 찾는다 — 따옴표 앞부분 안에 다른 받는 사람의 주소가 글자로 들어 있어도 그 사람은 빼지 않는다(2026-10-29 리뷰 2).
- 다시 내기는 20차례(뺀 주소 21개)까지다. 그래도 거절이 남고 받는 사람이 남아 있으면 사본을 지우고 400 VAL_001(21번째를 뺀 뒤 남은 사람이 없으면 MAIL_010).
- 남는 사람이 없으면 만든 사본을 지우고 400 MAIL_010(아래 "모두 거절"과 같다).
- 다시 낼 시간(발송 55초 안에서 10초 이상)이 모자라면 사본을 지우고 503 MAIL_001 — 아직 아무것도 제출하지 않았으니 같은 키로 다시 보내면 된다. 발송 응답은 사본 정리까지 56초 안이다(정리는 남은 시간 안에서, 남은 시간이 없어도 1초까지는 기다린다).
- 다시 낸 제출이 요청째 거절되면(메서드 오류 · HTTP 4xx — 엔진이 실행하지 않았다) 사본을 지우고 첫 제출과 같은 오류로 끝난다. 결과를 모르는 실패(시간 초과 · 연결 끊김 · 5xx)는 지우지 않는다 — 나갔을 수 있어 같은 키의 재시도가 맡는다(첫 제출과 같다).
- 거절 글에 우리 주소가 없으면 지금처럼 400 VAL_001.
- 전에는 envelope 을 주지 않아 엔진이 그런 주소를 아무 말 없이 빼고 나머지에게만 보냈다 — 오타 도메인으로 간 사람이 응답에 없었다.
- 결과(deliveryStatus)를 읽지 못해도 envelope 에서 뺀 사람은 rejectedRecipients 에 싣는다. 같은 키의 재시도는 제출 기록의 envelope 에 없는 받는 사람을 not-found 로 다시 만든다.
- 주소는 대소문자를 무시하고 국제화 도메인은 xn-- 꼴로 맞춘다 — 엔진은 유니코드 · xn-- 모두 받고 제출 기록에는 xn-- 로 둔다. 엔진의 거절 글은 로그에 남기지 않는다(뺀 주소만 가려서).
- 숨은참조: 엔진은 내보내는 사본(사내 배달 · 바깥 SMTP 모두)에서 Bcc 머리글을 뗀다 — 보낸 사본에만 남는다(envelope 을 주든 말든 같다). 개발의 Mailpit 은 받은 envelope 가운데 머리글에 없는 주소를 자기 Bcc: 줄로 맨 앞에 붙여 보인다 — 엔진이 보낸 것이 아니다(머리글 없는 메일을 envelope 으로만 보내도 그렇다).
모두 거절(받은 사람이 아무도 없음) — 보내지 않은 것으로 다룬다. 이 요청이 만든 보낸 사본은 지우고(아무에게도 가지 않았다 — 그 요청이 방금 만든 메일이라 조건 없이 지운다), 이어 쓴 저장본(draftId)은 지우지 않는다. 거절 가운데 5xx 가 하나라도 있으면 400 MAIL_010, 모두 4xx 면 503 MAIL_011. 같은 키로 다시 보내면 새로 보낸다(지운 사본은 중복 방지에 걸리지 않는다). 사본을 지우지 못해도(엔진 오류 — warn) 코드는 그대로다. 알려진 한계: 그때 보낸편지함에 사본 한 통이 남고, 같은 키 · 같은 내용의 재시도는 그 사본을 찾아 201 + 받는 사람 전원의 rejectedRecipients 로 답한다(이어 쓴 저장본도 지운다), 내용을 고친 재시도는 409 MAIL_005 다 — 지금 남은 결과만으로는 "제출 때 거절"과 "보낸 뒤 바깥에서 반송"을 가를 수 없어 다시 보내지 않는다. 제출 응답을 받지 못해 503 MAIL_001 로 끝났는데 엔진에서는 제출되어 모두 거절된 경우도 같다(사본을 지우는 데까지 가지 못했다) — 30초 잠금이 풀린 뒤 같은 키의 재시도가 그 사본을 찾는다.
일부 거절 — 보낸 것이다. 201 에 rejectedRecipients 를 싣고, 보낸 사본은 보낸편지함에 남고, draftId 는 지운다.
같은 키의 재시도가 처음 메일을 찾아 그대로 돌려줄 때도 그 메일의 제출 기록으로 rejectedRecipients 를 다시 만든다(찾지 못하면 빈 배열).
로그 — 모두 거절은 warn([MAIL_010] · [MAIL_011]), 일부 거절은 log. 주소는 가리고(maskEmail) SMTP 상태 코드(550 5.1.2 등)만 남긴다. MAIL_011 은 503 이라 전역 예외 필터가 5xx 규칙대로 error(스택 포함)로 한 줄 더 남긴다(MAIL_001 과 같다) — 웹메일 발송은 엔진 한도에 걸리지 않게 했으므로 드물다.
엔진 기본 한도 중 받는 사람 단위의 것("보낸 도메인 → 한 받는 사람" 시간당 25통)은 로그인한 직원의 발송에는 걸지 않는다 — 사내 메일은 보낸 도메인이 모두 같아, 동료 모두 합쳐 한 사람에게 시간당 25통을 넘으면 그 뒤가 거절되던 문제(같은 날 확인). mail setup 이 맞춘다(mail/README.md "엔진 한도"). 바깥에서 들어오는 메일(인증 없는 SMTP)에는 그대로 건다. 다른 기본 한도 "보낸 IP 마다 초당 연결 5개"는 연결할 때 세는 것이라 웹메일 발송에는 원래 걸리지 않고, 그대로 둔다 (조건을 붙이면 엔진이 그 한도를 연결이 아닌 MAIL FROM 단계로 옮겨 바깥 접속을 더는 세지 않는다 — Stalwart 0.16.27 소스로 확인).
클라이언트
- 일부 거절 — 보낸 것으로 처리한다(쓰기 화면을 닫고 떠난다). 보냈다는 알림 대신 실패 알림(「보낸편지함 보기」 링크 — 보냈다는 알림과 같은 글, 단추 있는 알림과 같은 10초)으로 "보냈지만 N명은 받지 못했습니다 — nobody@arasystem.it.kr (없는 주소)" — 두 명까지 주소와 까닭을 적고 더 있으면 " 외 N명". 까닭 문구는 not-found "없는 주소" · refused "받는 쪽이 거절" · temporary "지금은 받을 수 없음".
- MAIL_010 — 받는 사람 칸의 안내 띠(MAIL_002 와 같은 자리 · 같은 초점)로만 알린다(토스트 없음). 쓰던 메일 · 키는 그대로.
- MAIL_011 — 인터셉터 알림(사전 문구). 쓰던 메일 · 키는 그대로 — 잠시 뒤 다시 누르면 같은 키로 간다.

전달: 원본 메일 attachments[].id 를 발송 본문의 attachments 에 그대로 넣으면 원본 첨부가 다시 붙는다 (같은 계정 안의 파일이라 다시 올릴 필요가 없다). 제목 Fwd: 와 인용 본문은 클라이언트가 만들고, inReplyTo 는 보내지 않는다. 발송 본문의 첨부 이름(attachments[].name)은 업로드한 파일과 같은 규칙으로 확장자를 허용 목록에서 검사한다(밖이면 400 FILE_001) — 원본 첨부를 그대로 전달할 때도 같다.

답장·전달 초안의 길이: 클라이언트가 초안을 만들 때 한도에 맞춘다 — 제목은 255자, 본문은 텍스트 100,000자·서식 본문 500,000자. 넘으면 인용을 줄이고 끝에 생략 표시를 둔다 (본문을 넘긴 채 보내면 400 MAIL_007, 제목은 VAL_001). 처음 맞출 때는 쓸 글 몫으로 한도의 5%를 남기고(텍스트 95,000자·서식 475,000자), 보내기 직전에 실제로 보낼 본문을 다시 재서 넘으면 인용을 더 줄인다. 인용 없이 쓴 글만으로 넘으면 보내지 않고 쓰기 화면의 본문 아래에 MAIL_007 문구로 알린다 (서버가 MAIL_007 을 돌려줘도 같다).

서식 본문 (bodyHtml): 쓰기 화면의 서식 편집기가 만든 HTML 이다.

클라이언트는 같은 내용의 일반 텍스트를 body 로 함께 보낸다 (받는 쪽 프로그램이 텍스트만 볼 때 쓰는 대체 본문 — 목록은 - /1. , 인용은 > 를 붙인다). 서버는 둘을 multipart/alternative 로 보낸다. bodyHtml 이 없으면 텍스트 메일이다.
서버는 보내기 전에 허용 목록으로 정화한다 — 편집기가 만드는 것만 남긴다: 문단·줄바꿈, 굵게·기울임·밑줄·취소선, 글자 색·배경 색·글꼴·글자 크기(span 의 style), 정렬·들여쓰기·줄 간격, 목록, 인용, 가로줄, 표(칸 폭을 적는 colgroup·col 포함), 링크(http·https·mailto). 그 밖의 태그·속성·스타일·스크립트는 지운다. 지문에는 정화한 결과가 들어간다.
- 남는 속성: style(a 를 뺀 모든 태그), a 의 href(링크에는 이것만 남는다 — 링크 글자 색은 안쪽 span 의 style 로), ol 의 start, td·th 의 colspan·rowspan(숫자만).
- 남는 style: color·background-color·font-family·font-size·font-weight·line-height·text-align·margin·padding(각 변 포함)· border(각 변·border-color·border-style·border-width·border-collapse)·width·min-width·vertical-align·white-space.
- style 은 값의 형식까지 맞아야 남는다 — 형식이 틀린 선언은 그 선언만 지운다: 글자 크기는 px 만 899.99px, 색은 #rgb·#rrggbb·rgb()·rgba()(색 이름·hsl() 은 지운다) — 글자 색(color)의 투명도(알파)는 0.3 이상, 여백은 0 또는 px(음수 없음), 줄 간격은 단위 없는 숫자 13(소수 둘째 자리까지), 글꼴은 쓰기 화면의 글꼴 목록과 흔한 대체 이름(Helvetica·Times·Courier· AppleGothic·AppleMyungjo)·일반 이름(sans-serif·serif·monospace)으로만 이뤄진 목록.
- 형광 표시는 mark 가 아니라 span 의 background-color 로 보낸다 (mark·h1 같은 모르는 태그는 태그만 지우고 글자는 남긴다).
- 정화하고 남는 것이 없으면 body 만으로 텍스트 메일을 보낸다.
- 그림은 보내는 사람 자신의 서명 그림만 남는다 — <img src="/api/mail-signature/images/{id}"> 이고 그 id 가 보내는 사람의 그림일 때. 속성은 src·width(1~600, 숫자만)·alt(200자 이하)만 남는다. 서버가 그 그림을 메일 안에 함께 실어(multipart/related, cid:) 보내므로 받는 쪽에서 외부 이미지처럼 막히지 않는다. 그 밖의 img·찾지 못한 서명 그림(지운 그림)은 태그째 지운다. 클라이언트 편집기도 이 그림만 받는다.
- 보이지 않을 만큼 작은 글자(8px 미만)·거의 투명한 글자 색(알파 0.3 미만)은 그 선언을 지운다 — 붙여 넣거나 인용한 글에 그렇게 숨긴 글이 그대로 실려 나가지 않게. 바탕과 같은 색(흰 바탕 위 흰 글자 등)은 바탕을 알 수 없어 막지 않는다 (받은 메일을 읽을 때의 정화는 이 제한을 두지 않는다).
- 한도 — 넘으면 400 MAIL_007. 엔진·첨부 조회 전이라 메일은 나가지 않으므로, 고친 뒤 같은 키로 다시 보내면 된다. 정화 전에는 받은 메일과 같은 파서 비용 한도(위 "읽기 한도")를, 정화 뒤에는 결과가 UTF-8 2,000,000바이트 이하인지 본다 (우리 웹메일이 다시 읽을 때 잘리지 않게). 500,000자 안이어도 넘을 수 있다 — 정화가 & 를 &(5바이트)로 바꾸고, 한글은 글자당 3바이트·이모지는 4바이트다.
기본 글꼴은 맑은 고딕 이다 — 클라이언트가 본문 전체를 font-family·font-size:14px·line-height:1.75 를 가진 div 하나로 감싸 보낸다. 편집기 화면의 CSS 는 메일에 따라가지 않으므로 문단 여백(0)·인용 막대·표 테두리도 각 요소의 인라인 style 로 보낸다.
클라이언트도 같은 값 형식만 읽는다 — 붙여 넣은 글과 원문 인용을 편집기로 옮길 때 위 형식 밖의 서식(색 이름·font-size:0·목록에 없는 글꼴 등)은 버린다 (글자 크기의 pt 는 px 로 바꾼다). 서버만 지우면 편집기에서 숨은 글이 받는 사람에게 보이는 식으로 화면과 보낸 메일이 달라진다.
여러 칸 띄어쓰기와 줄 앞 공백은 받는 쪽이 합치거나 지우므로 nbsp 로 바꿔 보낸다 (보통 공백과 번갈아 — 긴 공백에서도 줄은 바뀐다). 탭은 다음 8칸 자리까지의 공백으로 바꾼다. 텍스트 대체 본문(body)은 그대로 둔다.
우리 웹메일이 다시 읽을 때(보낸편지함·받은 사람)도 이 서식이 남아야 한다 — 받은 메일 정화(htmlBody)의 허용 목록이 위 서식을 포함한다.
답장·전달의 원문 인용은 두 경우 모두 "원본 메일" 머리(보낸 사람·날짜·제목, 전달은 받는 사람·참조도)와 회색 인용 막대로 만든다. 원문은 htmlBody(없으면 textBody)를 편집기로 옮기며, 편집기가 모르는 요소(이미지 등)는 빠진다.
본문 안 이미지는 이번 단계에서 넣지 않는다 — 붙여 넣거나 끌어다 놓은 이미지는 첨부 파일로 올린다 (첨부 한도 규칙 그대로). 서명 그림만 예외다 (아래 "서명").

첨부 업로드 한도

파일당 MAIL_ATTACHMENT_MAX_SIZE_MB (기본 20MB) — 넘으면 413 FILE_002
메일 한 통의 첨부 합계(전달하는 원본 첨부 포함, 같은 첨부를 두 번 붙이면 두 번 센다) attachmentTotalMaxBytes (MAIL_ATTACHMENT_TOTAL_MAX_SIZE_MB, 기본 25MB) — 넘으면 발송이 413 FILE_002. 클라이언트는 첨부를 추가할 때 이 값으로 미리 막고 안내한다 (다 쓰고 보낼 때 알게 하지 않는다).
엔진의 임시 업로드 한도(7단계에 찾음): 계정마다 1시간 동안 올린 크기 합계 · 개수(Stalwart uploadQuota · maxUploadCount · uploadTtl). 엔진 기본값은 50MB · 1,000개 — 넘으면 올린 것이 만료될 때까지(1시간) 그 직원의 첨부 올리기와 필터 · 부재중 저장(엔진에 규칙 글을 올린다) · 서명 그림이 든 발송이 429 REQ_001 로 막힌다 (2026-10-29 개발 엔진: 1,000개를 넘기자 필터 저장이 막혔고, 20MiB 두 개 뒤 세 번째 업로드가 429 — 크기 · 개수 어느 쪽이든 같은 REQ_001, 백엔드 로그 "call":"upload"). 그래서 mail setup 이 크기 합계를 첨부 합계 한도의 20배(기본 25MB × 20 = 524,288,000바이트)로 둔다 — 개수(1,000)는 그대로(mail/README.md "엔진 한도").
허용 형식(확장자 + MIME 둘 다 검사): pdf · doc/docx · xls/xlsx · ppt/pptx · hwp/hwpx · txt · csv · png · jpg/jpeg · gif · webp · zip
다운로드는 <a href> 이동으로 받는다 — 같은 출처라 쿠키가 함께 간다. 이동은 axios 를 거치지 않아 401 재시도 규칙이 적용되지 않으므로, 이동하기 전에 세션을 확인한다 (/auth/me 가 AUTH_001 이면 /auth/refresh 한 번 → 실패하면 세션 만료 처리).

임시 저장 (`/api/drafts`)

interface Draft {
  id: string                 // 저장할 때마다 바뀐다 — 응답의 id 로 바꿔 쓴다
  to: Address[]
  cc: Address[]
  bcc: Address[]
  subject: string
  body: string               // 텍스트 대체 본문
  bodyHtml: string | null    // 서식 본문 — 보내는 정화를 거친 값 (없거나 비면 null). 다른 메일 프로그램이 만든 초안도 같은 정화를 거친다
  attachments: Attachment[]  // 이 판의 첨부 — id 가 저장할 때마다 바뀐다
  inReplyTo: string | null   // 답장할 메일 id (없거나 원 메일이 사라졌으면 null)
  updatedAt: string          // 마지막으로 저장한 시각 (ISO 8601 UTC)
}

interface DraftSaved { id: string; attachments: Attachment[]; updatedAt: string }

초안 본문은 발송 본문과 같은 필드·한도다(본문 길이 MAIL_007, 첨부 20개 MAIL_006, 첨부 합계 FILE_002, JSON 본문 4MB …). 다만 받는 사람은 0명이어도 되고 (합계 100명 이하), draftId 는 없다.
저장: 처음은 POST, 그다음은 PUT /api/drafts/{직전 id}. 메일은 고칠 수 없어 서버가 새 초안을 만들고, 다시 읽어 확인한 뒤 옛것을 지운다 — 클라이언트는 응답의 id·attachments 로 바꿔 쓴다. 서버는 초안에 발송 중복 방지용 Message-ID·지문 헤더를 넣지 않는다. 만들기와 지우기를 한 요청에 넣지 않는다 — 엔진은 같은 요청에서 만들기가 실패해도 지우기를 그대로 해서, 저장에 실패한 순간 저장본이 사라진다.
- "임시보관함의 초안" = 임시보관함에만 있고 $draft 이며 보내기 중에 생긴 내부 초안이 아닌 메일. PUT 의 id 가 그렇지 않으면(휴지통·보낸 메일 등) 아무것도 만들거나 지우지 않고 404 RES_001.
- 옛 초안이 이미 없으면(다른 창·기기에서 먼저 고쳤거나 지웠음) 409 MAIL_008 — 처음 확인에서 없으면 아무것도 만들지 않고, 만든 뒤 지우는 사이에 없어졌으면 방금 만든 것을 지운다.
- 클라이언트는 MAIL_008 과 PUT 의 404 RES_001(다른 창에서 휴지통으로 옮긴 경우 등)을 모두 막지 않고, 지금 내용을 POST 로 새로 남긴다.
- 옛것은 확인한 뒤로 메일함이 바뀌지 않았을 때만 지운다(JMAP ifInState, 엇갈리면 다시 확인 — 모두 세 번까지). 지우기는 되돌릴 수 없어서다. 그사이 다른 곳에서 옮겼으면 지우지 않고, 계속 엇갈리면 옛것이 한 통 더 남는다 (저장은 성공).
목록·버리기·되돌리기는 기존 API 다 — 목록 GET /api/messages?mailboxId=<임시보관함>(보내기 중에 생긴 내부 초안은 나오지 않는다), 버리기는 휴지통으로 옮기기 PATCH /api/messages/{id} { mailboxId: <휴지통> }(웹은 DELETE 를 쓰지 않는다 — 이미 휴지통인 메일은 DELETE 가 영구 삭제한다), 되돌리기 PATCH /api/messages/{id} { mailboxId: <임시보관함> }.
보내기: 이어 쓴 초안은 발송 본문에 draftId 를 넣어 보낸다. 서버는 지금의 발송 경로(정화·지문·중복 방지 그대로)로 보내고, 성공한 뒤 (같은 키 재시도로 처음 결과를 돌려줄 때 포함) 그 초안을 지운다 — 초안 자체를 그대로 제출하지 않는다. 지우기는 위 저장과 같은 조건(임시보관함의 초안 · 확인한 뒤 바뀌지 않음)일 때만 하고, 못 지우면 로그만 남긴다(발송은 성공). draftId 는 지문에 넣지 않는다.
클라이언트 저장 주기: 바꾼 내용이 있을 때 입력이 3초 멈추면 · 쉬지 않고 쓰는 중에도 30초마다 · 10초에 한 번까지 · 화면을 떠날 때, 한 번에 하나씩. 찾지 못한 첨부(MAIL_004)가 남은 동안과 본문이 한도를 넘는 동안은 저장하지 않는다 (첨부가 빠진 판으로 저장본을 덮지 않게). 다른 메일 프로그램이 만든 저장본에 실을 수 없는 첨부(허용 목록 밖 · 개수 · 합계 초과)가 있으면 첫 저장은 PUT 이 아니라 POST 다 — 원본을 지우지 않는다. 보내기 전에는 진행 중인 저장을 기다린다 (그래야 draftId 가 최신이다).
알려진 한계:
- 저장할 때마다 첨부 내용이 새 초안으로 복사돼 큰 첨부가 있으면 저장이 무겁다. 메일함 용량이 거의 차면 교체하는 순간 두 판이 함께 있어 MAIL_003 이 날 수 있다.
- 답장 대상은 초안의 사용자 머리 X-Ara-Reply-To-Id(메일 id)에 둔다. 우리 서버는 보낼 때 새 메일을 만들어 이 머리가 나가지 않지만, 다른 메일 프로그램이 그 초안을 그대로 보내면 함께 나갈 수 있다.
- 보내기에서 제출은 됐지만 보낸편지함으로 옮기지 못한 메일은 임시보관함에 보이지 않는 채로 남는다 (같은 키의 재시도는 그 메일을 찾는다).
- 저장 응답을 받지 못하면(시간 초과 등) 서버는 이미 새 저장본을 만들었을 수 있다 — 다음 PUT 은 MAIL_008 이 되어 클라이언트가 새로 남기므로 임시보관함에 한 통이 더 남을 수 있다 (잃는 내용은 없다).

서명 (`/api/mail-signature`)

interface MailSignature {
  bodyHtml: string | null    // 서명 서식 — 서식 본문 규칙 + 서명 그림. 정화 뒤 10,000자 이하
  body: string | null        // 텍스트 서명 (텍스트 대체 본문에 넣는다) — 2,000자 이하
  isForNew: boolean          // 새 메일에 넣는다 (기본 true)
  isForReply: boolean        // 답장·전달에 넣는다 — 인용 위 (기본 true)
  images: SignatureImage[]   // 서명이 쓰는 그림
  updatedAt: string | null   // 저장한 적 없으면 null
}

interface SignatureImage {
  id: string
  type: 'image/png' | 'image/jpeg' | 'image/gif'
  size: number               // 바이트
  width: number              // 원본 픽셀
  height: number
}

사용자마다 하나다. 저장한 적 없으면 기본값(bodyHtml: null·body: null·둘 다 true·images: [])을 돌려준다. 서버 DB 에 둔다(메일 엔진에 두지 않는다).
PUT 의 한도 — 넘으면 400 VAL_001: 텍스트 서명 2,000자, 서식 서명은 정화 전에 서식 본문과 같은 한도(500,000자·파서 비용)와 정화 뒤 10,000자, 서명 그림 3장(서로 다른 그림 기준).
서명 그림: POST /api/mail-signature/images (multipart file) — PNG·JPEG·GIF 만(확장자·MIME·파일 앞부분 모두 검사, WebP·SVG 는 받지 않는다), 한 장 300KB 이하(넘으면 413 FILE_002 — 받은 메일의 본문 그림 한도와 같아서, 보낸 메일을 우리 웹메일로 다시 읽어도 그림이 보인다), 가로·세로 각각 4096px 이하(넘으면 400 FILE_001 — 작은 파일 안의 아주 큰 그림이 받는 쪽을 무겁게 하지 않게). 서명에는 3장까지 넣는다(편집기가 먼저 막는다). 발송 본문·임시 저장본도 서로 다른 서명 그림 3장까지다(넘으면 400 VAL_001). 올려 두기만 한 그림을 포함해 한 사람 10장까지 둘 수 있다(넘으면 올리기가 400 VAL_001). 서명 HTML 은 그림을 <img src="/api/mail-signature/images/{id}" width="144" alt=""> 로 가리킨다(width 1~600 — 작게 96 · 보통 144 · 원본은 원래 폭, 600 이하).
GET /api/mail-signature/images/{id} 는 그 사람의 그림만 내준다(남의 것은 404 RES_001) — 편집기·미리 보기용이고, 받는 사람은 이 주소를 쓰지 않는다. 저장할 때 확인한 형식 그대로, Content-Disposition: inline · X-Content-Type-Options: nosniff · Cache-Control: private, max-age=86400 (그림 id 의 내용은 바뀌지 않는다 — 새로 올리면 새 id).
PUT 은 서명 HTML 이 더는 가리키지 않는 그림을 지운다 — 다만 한 번도 저장하지 않은 그림 가운데 10분 안에 올린 것은 남긴다 (그림을 넣자마자 저장하면 올리기와 저장이 엇갈릴 수 있다). 올리고 저장하지 않은 그림은 하루 뒤 지운다.
보낼 때: 쓰기 화면이 서명을 본문에 보통 글로 넣어 둔 그대로 보낸다 — 서명 그림은 위 "서식 본문"의 그림 예외로 메일 안에 함께 실린다 (multipart/related 의 그림 부분 — Content-Disposition: inline, Content-ID: <sig-{그림 id}@{보내는 사람 도메인}>, 이름 signature-1.png …, 첨부가 있으면 그 묶음을 multipart/mixed 안에 둔다). 우리 웹메일에서는 위 hasAttachment·isInline 규칙으로 첨부로 보이지 않는다. 텍스트 대체 본문에는 그림이 없다. 임시 저장본도 같은 그림 주소를 쓴다.
알려진 한계: 서명 그림을 지운 뒤 그 그림을 쓴 임시 저장본을 보내면 그 그림은 빠진다. 답장·전달로 인용한 원문 속 그림(남의 서명 로고 포함)은 인용에서 빠진다.

받는 사람 추천 (`/api/recipient-suggestions`)

interface RecipientSuggestion {
  name: string | null
  email: string
  source: 'contact' | 'directory' | 'recent'   // contact = 내 주소록(8단계), directory = 사내(8단계부터 엔진의 사내 목록 — 3절), recent = 최근 주고받은 주소
  company: string | null                          // contact 만 — 그 연락처의 회사 (그 밖에는 null)
  emailLabel: 'work' | 'personal' | 'other' | null   // contact 만 — 그 주소의 종류 (그 밖에는 null)
}

q 가 있으면 이름·주소에 그 글자가 든 것만 준다(대소문자 무시). 8단계부터 쓰기 화면과 같은 맞추기다 — 이름은 초성 · 조합 중 글자를 섞어도 맞고 (ㄷㅇ · 도ㅇ → 이도윤, 윤을 치는 중인 도유 · 동 → 도윤), 주소는 그 글자가 든 것(완전한 주소를 쳤으면 같은 아이디도). 규칙의 짝은 frontend shared/utils/recipient-match.ts 이고 두 쪽 테스트가 같은 표본 표를 쓴다. 응답은 커서 페이지네이션 규칙 그대로({ items, pageInfo }) — 커서는 받은 그 q 로만 쓴다(다른 q 와 함께 보내면 400 VAL_001).
순서: 주소록(8단계) → 사내 → 최근 주고받은 주소. 주소록은 이름 차례(3절), 사내 · 최근은 주고받은 횟수와 최근성으로. 여러 묶음에 있는 주소는 앞 묶음으로 한 번만 나온다 — 3절 "메일과 함께".
최근 주고받은 주소는 그 사람의 보낸편지함 최근 500통(받는 사람·참조·숨은참조)과 받은편지함 최근 500통(보낸 사람)에서 모은다 — 다른 직원의 메일함은 읽지 않는다. 나·메일 엔진 관리자·게이트웨이·막은 계정·noreply 류는 뺀다.
사내 목록은 8단계부터 엔진의 사내 목록(3절 "사내 목록")이다. 그것을 읽지 못할 때만 아래 옛 규칙으로 대신한다 — 로그인에 성공한 직원(주소·이름)을 서버가 기록해 만든다(직원 역할에는 엔진의 계정 목록 권한이 없다). 한 번도 로그인하지 않은 직원은 그 사람과 메일을 주고받기 전까지 나오지 않는다. 최근 90일 안에 로그인한 직원만 사내로 추천한다 (퇴사자가 계속 맨 앞에 나와 반송되지 않게 — 웹메일 세션은 최대 30일이라 쓰는 사람은 그 안에 다시 로그인한다).
알려진 한계: 최근 주고받은 주소의 이름은 받은 메일의 보낸 사람 표시 이름에서 온다 — 바깥 사람이 동료 이름을 표시 이름으로 쓰면 그 이름으로 추천된다. 추천 줄은 늘 주소를 함께 보이고, 사내와 최근 묶음을 나눠 보인다.
응답은 Cache-Control: private, no-store. 서버는 사용자마다 10분 캐시하고(서버 메모리, 최대 500명), 그 사람이 메일을 보내면 다시 모은다. 같은 사람의 동시 요청은 한 번만 모은다. 로그에는 개수만 남긴다.
클라이언트: 쓰기 화면을 열 때 q 없이 limit=100 으로 한 번 받아 두고 치는 대로 거른다(초성 포함). 맞는 것이 모자라고 더 있을 때만 q 로 다시 묻는다(250ms 기다린 뒤) — 8단계부터는 초성 · 조합 중 글자도 묻는다(주소록이 크면 받아 둔 100줄이 주소록으로 차서 사내 · 최근 주소가 그 안에 없다). 맞추기가 같아서 받아 둔 것에서 8개를 찾았으면 서버에 물어도 같은 8개다. 두 쪽 모두 유니코드 정규형(NFC)으로 맞추지 않는다 — 화면이 원래 글자 위치로 강조하기 때문이다(다른 정규형으로 저장된 이름은 그 글자로 맞지 않는다).

새 메일 확인 (`/api/mail-state`) — 3단계

// GET /api/mail-state — 새 메일 · 다른 창(메일 프로그램)의 변화를 알아채는 데 쓴다
interface MailState {
  state: string   // 불투명 — 메일함이나 메일이 하나라도 바뀌면 달라진다. 해석하지 말고 지난 값과 같은지만 본다
}

서버는 엔진의 메일함 · 메일 상태 문자열을 이어 붙여 돌려준다 (JMAP Mailbox/get · Email/get 에 ids: [] — 메일을 읽지 않는 가벼운 조회). 새 메일이 오거나 다른 창 · 메일 프로그램이 읽음 · 이동 · 삭제를 하면 값이 바뀐다 (2026-10-27 개발 엔진에서 확인). 응답은 Cache-Control: private, no-store.
클라이언트: 로그인한 동안, 화면이 보이는 동안(visibilityState === 'visible')만 60초마다 묻는다. 탭이 다시 보이면 마지막으로 물은 지 10초가 지났을 때 바로 한 번. 한 번에 하나씩.
- 처음 받은 값은 기준으로만 쓴다. 값이 바뀌면 메일함 개수 · 사용량을 다시 받고, 보이는 메일함 목록을 지금까지 불러온 만큼(최대 100통) 다시 받아 맞춘다 — 고른 메일 · 열린 메일 · 스크롤 위치는 그대로. 100통보다 많이 불러왔으면 첫 100통만 맞추고 그 뒤는 둔다. 검색 결과는 다시 찾지 않는다(보던 결과가 저절로 바뀌지 않게).
- 이 탭이 바꾼 것(읽음 · 이동 등)도 값을 바꾸므로 다음 확인에서 한 번 더 받게 된다 — 해롭지 않다.
- 실패(MAIL_001 · 네트워크)는 알리지 않고(silent) 다음 주기에 다시 묻는다. 401 은 지금의 세션 흐름(갱신 1회 → 만료 대화상자)을 그대로 탄다.
- 받은편지함에 안 읽은 메일이 있으면 탭 제목 앞에 (N) 을 붙인다 (디자인 README "3단계").
요청 수 한도(THROTTLE_LIMIT, 기본 1분 100회)는 경로마다 · IP 마다 센다 — 사무실 전체가 한 IP 로 나가면 보이는 탭이 100개를 넘을 때 1분 확인이 429 REQ_001 로 조용히 실패한다(다음 주기에 다시). 값이 바뀌었을 때의 맞추기(GET /api/messages · /api/mailboxes · /api/mail-quota)는 평소 사용과 같은 칸을 쓴다 — GET /api/messages 는 대략 "쓰고 있는 탭 수 × 1분에 1번 + 평소 목록 · 더 보기"다(3단계). 5단계부터는 실시간 연결이 살아 있는 동안 1분 확인 대신 "바뀔 때마다(1초 모아서) 보이는 탭 수 × 1번"이다 — 사무실이 바쁠수록 늘 수 있다. 운영 전환 때 직원 수에 맞춰 정한다.
5단계부터는 실시간 연결(아래 "실시간 알림")이 살아 있는 동안 1분 확인을 멈추고, 끊기면 1분 확인으로 돌아간다. 이 API 와 규칙은 그대로다.

검색 (`GET /api/messages` 의 `q`) — 3단계

mailboxId 가 있으면 그 메일함에서, 없으면 휴지통 · 스팸메일함을 뺀 모든 메일함에서 찾는다. 둘 다 없으면 400 VAL_001.
q 는 앞뒤 공백을 뺀 1~200자(JS 문자열 길이 — UTF-16 단위), 낱말(띄어쓰기로 나눈 것) 8개까지(넘으면 400 VAL_001). 보낸 사람 · 받는 사람 · 참조 · 제목 · 본문에서 찾고, 여러 낱말이면 모두 들어간 메일만 찾는다. 큰따옴표로 감싼 부분은 그 구절 그대로 찾는다. 낱말 앞뒤의 문장부호는 떼고 찾는다('회의,' · '(회의)' → '회의' — 엔진도 문장부호에서 낱말을 나눈다, 가운데의 문장부호는 둔다). 글자 · 숫자가 하나도 없는 낱말(- · 따옴표뿐 등)은 찾지 않고, 찾을 낱말이 하나도 남지 않으면 엔진에 묻지 않고 빈 결과(200)다.
한국어 — 서버가 보완한다: 엔진(Stalwart 0.16.27)의 전문 검색은 띄어쓰기 · 문장부호로 나눈 낱말이 통째로 같을 때만 맞는다 — '회의'로는 '회의를'을 찾지 못한다 (2026-10-27 개발 엔진에서 확인). 그래서 서버는 한글로 끝나는 낱말마다 흔한 조사를 받침에 맞게 붙인 형태를 함께 찾는다 (회의 → 회의가 · 회의를 · 회의는 · 회의에서 · 회의입니다 … / 일정 → 일정이 · 일정을 · 일정은 …, 낱말 안에서는 OR · 낱말끼리는 AND). 영문 · 숫자로 끝나는 낱말(ERP · 2026)은 받침을 알 수 없어 두 가지를 다 붙인다. 따옴표 구절에는 붙이지 않는다. 조사 목록은 서버 상수 한 곳(jmap/search-terms.ts)에 둔다 — 한글로 끝나는 낱말은 형태 44개, 영문 · 숫자로 끝나면 59개가 되고, 개발 엔진에서 낱말 8개(조건 472개)를 전체 메일함에서 찾는 데 0.16초였다.
알려진 한계 (엔진 색인 때문 — 자체 검색 색인을 두기 전까지): 붙여 쓴 말의 일부('회의실'의 '회의', '서버이전'의 '서버'), 앞부분만 친 말('견적' → '견적서'), 끝이 바뀐 말('보냈습니다'의 '보내'), 제목 맨 앞의 말머리('[공지]' · '[긴급]' · 'Re:' · 'Fwd:' — 엔진이 제목을 정규화하며 색인에서 뺀다. 제목 가운데의 '[결재]'는 찾는다). 화면은 결과가 없을 때 이 한계를 한 줄로 알린다.
결과는 받은 시각 내림차순, total 포함. 커서는 그 검색어 · 범위로만 쓴다(다르면 400 VAL_001). 발송 중인 내부 초안은 지금처럼 빠진다.
검색어는 접근 로그 · 백엔드 로그에 남기지 않는다 — 백엔드는 지금처럼 maskUrlForLog()(q · cursor 는 길이만). 화면 주소에도 검색어가 들어가므로 nginx 는 /api 뿐 아니라 화면 요청의 접근 로그도 쿼리 없이 남기고(Referer 도 ? 앞까지), 화면 응답의 Referrer-Policy 를 strict-origin 으로 둔다 — 검색 화면에서 나가는 요청(1분 확인 등)의 Referer 에 검색어가 실리지 않게. 오류 로그는 장애 원인 줄을 잃지 않게 지금처럼 요청 줄을 쿼리째 남긴다 (docker 스킬 "로그").
클라이언트: 상단 검색 칸(메일 화면에서는 "메일 검색")에서 Enter 로 찾는다 — 치는 동안에는 묻지 않는다. 서버와 같은 한도(200자 · 낱말 8개)를 먼저 보고, 낱말이 8개를 넘으면 보내지 않고 VAL_001 사전 문구로 알린다. 검색 화면 안에서 다시 찾거나 범위를 바꾸면 방문 기록을 쌓지 않고 주소를 바꿔 끼운다(메일함에서 시작한 첫 검색만 기록에 쌓인다). 주소는 /mail/search?q=…&in=<메일함 id | all>, 결과에서 연 메일은 /mail/search/<메일 id>?q=…&in=… (뒤로 가기: 메일 → 결과 → 검색 전 메일함). 범위의 기본값은 검색을 시작한 메일함이고 결과 머리에서 "그 메일함 | 전체 메일함"으로 바꾼다(휴지통 · 스팸메일함에서 시작하면 그 안에서 찾는다). ✕ · Esc · "검색 닫기"는 검색 전 메일함으로 돌아간다. 임시보관함의 결과를 누르면 지금처럼 쓰기 화면에서 이어 쓴다.

여러 통 한꺼번에 (`PATCH /api/messages` · `POST /api/message-deletions`) — 3단계

// PATCH /api/messages — 읽음 · 중요 표시 · 이동을 여러 통에
interface MessagesPatch {
  ids: string[]          // 1~100, 같은 id 를 두 번 넣지 않는다
  isRead?: boolean
  isFlagged?: boolean
  mailboxId?: string     // 이동 = 그 메일함 하나에만 속하게 (단건 PATCH 와 같다)
}                        // 바꿀 것이 하나 이상
interface MessagesPatched {
  updatedIds: string[]
  failedIds: string[]    // 없음 · 그사이 지워짐 · 엔진이 거절함 — 나머지는 그대로 처리한다
}

// POST /api/message-deletions — 휴지통에서 영구 삭제, 여러 통
interface MessageDeletionRequest { ids: string[] }   // 1~100, 같은 id 를 두 번 넣지 않는다
interface MessageDeletionResult {
  deletedIds: string[]   // 영구 삭제했다(휴지통에만 있었다) · 휴지통에서만 뺐다(다른 메일함에도 있었다)
  skippedIds: string[]   // 휴지통에 없음 · 없음 · 엔진이 거절 — 지우지 않았다
}

PATCH /api/messages 는 엔진 요청 한 번으로 처리한다. 없는 mailboxId 는 404 RES_001 이고 아무것도 바꾸지 않는다. 503 MAIL_001 이면 일부만 바뀌었을 수 있다 — 같은 요청을 다시 보내도 결과가 같다(멱등).
POST /api/message-deletions 는 휴지통에 있는 메일만 다룬다 — DELETE /api/messages/{id} 와 달리 휴지통 밖의 메일을 휴지통으로 옮기지 않는다. 대상을 확인한 뒤 확인한 상태 그대로일 때만 한 번에 지운다(ifInState — 그사이 다른 창이 휴지통 밖으로 되돌린 메일을 지우지 않는다). 어긋나면 다시 확인해 합계 CONDITIONAL_DESTROY_ATTEMPTS 번, 계속 어긋나면 아무것도 지우지 않고 503 MAIL_001. 휴지통이 없어도 503 MAIL_001. 지우는 요청이 엔진 시간 초과로 끝난 503 MAIL_001 만은 일부가 지워졌을 수 있다 — 같은 요청을 다시 보내면 이미 지운 메일은 skippedIds 로 온다. 한 번에 지우기(destroy)와 휴지통에서 빼기(update)를 함께 보내고, 옛 상태면 엔진이 둘 다 거절한다 (2026-10-27 개발 엔진에서 확인).
한 요청의 ids 는 100개까지다 (엔진의 한 번 처리 한도 500 보다 작게).
클라이언트:
- 고를 수 있는 것은 불러온 메일까지다 (표 머리의 고르기 = 불러온 메일 모두). 100통이 넘으면 100통씩 차례로 보낸다.
- 휴지통 밖의 「삭제」는 PATCH { mailboxId: 휴지통 } 이다 — 「되돌리기」는 원래 메일함별로 묶어 다시 PATCH. POST /api/message-deletions 는 휴지통에서 「영구 삭제」를 확인한 뒤에만 부른다.
- 웹 클라이언트는 DELETE /api/messages/{id} 를 쓰지 않는다 — 그사이 다른 창이 휴지통으로 옮긴 메일을 확인 없이 영구 삭제하게 된다. 읽기 화면의 「삭제」도 그 메일의 mailboxIds 를 보고 휴지통 밖이면 휴지통으로 PATCH(+ 되돌리기), 휴지통이면 확인 대화상자 뒤 POST /api/message-deletions 다. 휴지통 목록 밖(검색 결과 등)에서는 휴지통에만 있는 메일만 「영구 삭제」다 — 휴지통과 다른 메일함에 함께 있는 메일은 「삭제」(휴지통으로 옮기기)로 다룬다 (영구 삭제를 확인했는데 서버가 휴지통에서만 빼고 다른 메일함에 남기는 일이 없게). mailboxIds 가 낡았어도 해가 없다 — 이미 휴지통인 메일을 휴지통으로 옮기면 그대로이고, 휴지통 밖으로 돌아간 메일은 서버가 skippedIds 로 건너뛴다.
- 알려진 한계: 「되돌리기」는 이 화면이 알던 메일함 한 곳으로 되돌린다 — 그사이 다른 창이 옮긴 메일(저절로 바뀌지 않는 검색 결과 등)은 그 전 메일함으로, 여러 메일함에 함께 있던 메일(다른 메일 프로그램의 복사)은 첫 메일함으로만 돌아간다.
- 「되돌리기」 알림은 만든 세션에서만 움직인다 — 로그아웃 · 세션 만료 · 다른 계정 로그인 뒤에는 아무것도 하지 않는다(메일 id 는 계정마다 따로 매겨져 겹칠 수 있다).
- 읽음 · 중요 표시는 화면을 먼저 바꾸고 failedIds 만 되돌린다. 이동 · 삭제는 응답을 받은 뒤 updatedIds · deletedIds 만 목록에서 빼고 개수를 다시 맞춘다 (전체 메일함 검색 결과에서 범위 안의 다른 메일함으로 옮긴 메일은 여전히 찾은 메일이라 빼지 않고 메일함 표시만 바꾼다 — 휴지통 · 스팸메일함으로 옮기면 뺀다). 요청이 통째로 실패해 하나도 처리하지 못하면 고른 것을 그대로 둔다(다시 시도할 수 있게).
- failedIds · skippedIds 가 있으면 알림에 "N통은 그사이 옮겨졌거나 지워져 그대로 두었습니다"를 덧붙인다.
- 메일함을 바꾸거나 검색하면 선택을 푼다. 새 메일 확인으로 목록을 맞출 때는 남아 있는 메일의 선택을 그대로 둔다.

메일함 관리 (`/api/mailboxes`) — 4단계

interface MailboxCreate { name: string; parentId?: string | null }   // parentId 없음 = 맨 위
interface MailboxRename { name: string }
interface MailboxDeletion {
  deleted: boolean        // true = 지웠다. false = 아직 옮길 메일이 남았다 — 같은 요청을 다시 보낸다
  processed: number       // 이번 요청에서 이 메일함에서 빠진 메일 수 — 휴지통으로 옮김 + 다른 메일함에도 있어 이 메일함에서만 뺌 (진행 표시용)
  movedToTrash: number    // 그중 휴지통으로 옮긴 수 (끝난 알림의 "안의 메일 N통은 휴지통에 있습니다")
  remaining: number       // 아직 남은 메일 수
}
interface MailboxBulkResult {
  processed: number       // 이번 요청에서 읽음으로 바꾼 · 지운 메일 수
  remaining: number       // 남은 수 — 0 이 될 때까지 같은 요청을 다시 보낸다
}

이름: 앞뒤 공백을 뺀 1~64자(JS 문자열 길이), / 는 쓰지 않는다(경로 구분자로 읽는 메일 프로그램이 있다). 제어 문자도 쓰지 않는다 — C0(U+0000–U+001F, 탭 · 줄바꿈 포함) · DEL(U+007F) · C1(U+0080–U+009F). 그 밖의 문자(NBSP · 이모지 등)는 받는다. 같은 상위 안에 같은 이름은 409 MAIL_009 (엔진이 alreadyExists 로 거절한다 — 2026-10-28 확인). 지금 이름으로 바꾸면 엔진에 묻지 않고 그대로 돌려준다. 만든 메일함은 구독 상태(isSubscribed)라 IMAP 메일 프로그램에도 보인다.
만들 수 있는 자리: 맨 위, 받은편지함 · 보관함 · 내 메일함(역할 없음) 아래. 보낸편지함 · 임시보관함 · 스팸메일함 · 휴지통 아래는 400 VAL_001. 웹 화면은 받은편지함 · 내 메일함 아래만 메뉴에 둔다(보관함 아래는 다른 메일 프로그램이 만든 것을 그대로 보인다).
기본 메일함(역할이 있는 메일함)은 이름을 바꾸거나 지울 수 없다 — 400 VAL_001. 화면은 메뉴에 그 항목을 두지 않는다.
지우기: 하위 메일함이 있으면 400 VAL_001(화면이 먼저 막는다). 안의 메일은 휴지통으로 옮긴 뒤(다른 메일함에도 있는 메일은 이 메일함에서만 뺀다) 빈 메일함을 지운다 — 엔진은 메일이 든 메일함을 mailboxHasEmail 로 거절하므로(onDestroyRemoveEmails: false — 메일을 영구 삭제하는 옵션은 쓰지 않는다) 그사이 들어온 메일도 남지 않는다. 메일이 많으면 한 요청에 다 옮기지 못한다 — deleted: false 면 클라이언트가 같은 요청을 다시 보낸다.
전체 읽음(PATCH /api/mailboxes/{id}/messages {isRead:true}): 안 읽은 메일을 500통씩 읽음으로 바꾼다. 비우기(DELETE /api/mailboxes/{id}/messages): 휴지통 · 스팸메일함만, 500통씩 확인한 상태 그대로일 때만(ifInState) 영구 삭제한다 — 그 메일함에만 있는 메일은 지우고, 다른 메일함에도 있는 메일은 그 메일함에서만 뺀다(POST /api/message-deletions 와 같은 규칙).
오래 걸리는 처리(전체 읽음 · 비우기 · 메일함 지우기)는 한 요청을 25초 안에 끝내고(엔진 호출마다 남은 시간만큼만 기다린다) remaining 을 돌려준다. 클라이언트는 0(또는 deleted: true)이 될 때까지 다시 보내며 진행을 알림으로 보인다("…하는 중 · 600 / 1,234통"). 도중에 실패하면 거기까지 처리한 수를 알리고, 다시 하면 남은 것만 처리한다.
- 같은 직원 · 같은 메일함의 처리는 한 번에 하나다 — 진행 중이면 엔진에 묻지 않고 429 REQ_001(다른 탭에서 같은 메일함을 처리할 때). 다른 메일함끼리는 함께 된다.
- 한 요청의 상한 25초는 메일함 목록을 읽기 전부터 잰다(엔진의 세션 조회 포함). 다음 500통은 남은 시간이 5초보다 많을 때만 시작한다.
- 멈추는 경우 — 진행한 것이 있으면 거기까지 200(remaining > 0 · deleted: false), 하나도 처리하지 못했으면 503 MAIL_001(클라이언트가 끝없이 다시 보내지 않게): 아무것도 바뀌지 않는 차례(확인하는 사이 계속 바뀜 · 바뀐 것도 거절도 없음 · 비운 메일함을 지우는 사이 메일이 들어옴)가 이어서 3번, 남은 시간 때문에 엔진 호출이 끊김. 엔진이 한 차례를 모두 거절하면 진행한 것이 없을 때 그 거절의 코드(권한 없음 403 AUTH_003 등)다.
- 비우기는 차례마다 그 시점의 메일함을 다시 읽는다 — 비우는 동안 들어온 메일(새 스팸, 다른 탭에서 휴지통으로 옮긴 메일)도 지운다(흔한 메일 프로그램과 같다). 그래서 화면은 휴지통 비우기와 메일함 지우기(안의 메일이 휴지통으로 간다)를 함께 돌리지 않는다.
클라이언트: 메일함 패널의 각 메일함 ⋯ 메뉴 — 모두 읽음으로 표시(안 읽은 메일이 있을 때) · 하위 메일함 만들기 · 이름 바꾸기 · 지우기(내 메일함만) · 휴지통 / 스팸메일함 비우기. 휴지통 · 스팸메일함 목록 머리에도 「비우기」. 비우기 · 지우기는 확인 대화상자(처음 초점 「취소」) 뒤에만 하고, 확인한 그 메일함만 처리한다. 다른 탭에서 먼저 끝냈으면 실패로 보이지 않는다 — 모두 읽음 · 비우기의 0통은 "…에 안 읽은 메일이 없습니다" · "…이 이미 비어 있습니다", 지우기의 404 RES_001 은 지운 것으로 본다. 메일함 지우기의 진행은 processed 로 센다(movedToTrash 는 휴지통으로 간 것만이라 다른 메일함에도 든 메일만 남으면 늘지 않는다).

부재중 자동 응답 (`/api/mail-vacation`) — 4단계

interface MailVacation {
  isEnabled: boolean
  fromDate: string | null   // ISO 8601 UTC — null 이면 켠 때부터
  toDate: string | null     // null 이면 끌 때까지
  subject: string           // 켤 때 150자까지(꺼 둔 채로는 200자까지 — 아래 "길이 한도의 근거") — 켤 때(isEnabled true)는 공백이 아닌 글자 1자 이상. 제어 문자(메일함 이름과 같은 범위 — 탭 · 줄바꿈 포함)는 쓰지 않는다(한 줄짜리 머리글)
  textBody: string          // 켤 때 600자까지(꺼 둔 채로는 4,000자까지) — 켤 때는 공백이 아닌 글자 1자 이상. 글자만(서식 없음) — 제어 문자는 탭 · LF · CR 만. 서명은 붙지 않는다
}
interface MailVacationState extends MailVacation {   // GET · PUT 의 응답 (7단계)
  isActive: boolean         // false = 엔진에서 우리 규칙(필터와 한 스크립트)이 꺼져 있어 켜 둔 자동 응답이 지금은 동작하지 않는다 — 저장하면 다시 켜진다.
                            // 메일 필터의 isActive 와 같은 값(한 번도 저장하지 않은 계정은 true). PUT 본문에는 넣지 않는다(넣으면 400 VAL_001 — 모르는 필드)
}

길이 한도의 근거 (6단계 앞 수정): 엔진이 UTF-8 바이트로 막는다 — 제목 511바이트(한글 170자 · 영문 511자), 본문 2,047바이트(한글 682자 · 영문 2,047자) (Stalwart 0.16.27, 2026-10-28 확인 — 넘으면 엔진이 invalidProperties 로 거절해 400 VAL_001 이었다. 4단계 계약의 200자 · 4,000자는 한글로는 맞지 않았다). 글자마다 바이트가 달라(한글 3 · 이모지 4바이트/2자) 어떤 글이어도 넘지 않는 150자 · 600자로 둔다(JS 문자열 길이). 이 한도는 켤 때만 본다 — 꺼 둔 채로는 4단계 한도(200자 · 4,000자)까지 받는다. 4단계에 엔진 한도 안으로 저장해 둔 긴 글(영문 내용 1,000자 등)이 켜져 있으면 화면은 꺼 둘 때 칸이 흐려 고칠 수 없는데, 끄기는 늘 저장되어야 하기 때문이다. 다시 켤 때 150 · 600 에 걸리면 줄인 뒤 켠다.
한 번도 설정하지 않은 계정은 { isEnabled: false, fromDate: null, toDate: null, subject: "", textBody: "" } 로 온다(엔진의 null 은 빈 문자열로). 끈 채로는 빈 제목 · 내용도 저장된다. 제목 · 내용은 쓴 그대로 저장한다 — "공백이 아닌 글자" 검사만 앞뒤 공백을 뺀 값(JS trim() — NBSP · U+3000 포함)으로 한다. 제어 문자 검사는 꺼 둔 채로도 한다.
저장 자리 — 6단계부터 메일 필터와 같은 엔진 규칙(Sieve 스크립트 arasystem)에 둔다(아래 "메일 필터"의 "저장 자리"). 4단계에는 엔진의 JMAP VacationResponse(singleton)였다. 서식 본문은 없다(글자만). 저장은 전체 교체이고 응답은 저장한 값이다. 꺼도 쓴 제목 · 내용은 남겨 둔다. 필터와 한 스크립트라서 부재중을 저장해도 스크립트를 다시 켠다(필터가 꺼져 있었으면 함께 다시 동작한다). 필터 규칙은 건드리지 않는다.
- 6단계부터 바뀐 동작: 엔진이 스팸으로 분류한 메일에는 답하지 않는다(필터와 같은 스팸 막기 — "메일 필터"의 "만드는 Sieve").
- 우리 스크립트가 엔진에서 꺼져 있으면(isActive: false) 부재중도 동작하지 않는다 — isEnabled 는 저장한 값이라 그때도 true 다. 7단계부터 응답의 isActive 로 알린다 — 화면은 켜 두었을 때 머리 아래 줄 "켜 둔 자동 응답이 지금은 동작하지 않습니다. 메일 서버의 규칙이 다른 곳에서 바뀌었습니다 — 아래 [저장]을 누르면 다시 켜집니다."(단추 없음 — 저장 단추는 늘 누를 수 있다. 6단계의 알려진 한계를 고쳤다).
- 저장해 둔 원본이 깨진 계정은 꺼짐(isEnabled: false, 빈 제목 · 내용)으로 온다. 원본이 이 서버보다 새 판이면 저장은 503 MAIL_001 이다("메일 필터"의 "저장 자리").
fromDate · toDate 는 Z 로 끝나는 UTC 시각이고, 두 키는 늘 보낸다(값은 null 가능). 엔진에는 초 단위로 저장한다(소수 초는 버린다). 둘 다 있으면 버린 값으로 fromDate < toDate(아니면 400 VAL_001). 화면은 날짜만 고르고, 브라우저 시간대의 시작일 0시 · 끝나는 날 다음 날 0시를 UTC 로 보낸다.
같은 사람에게 매번 답하지는 않는다 — JMAP 규격(RFC 8621 8절)이 "보낸 사람마다 적당한 기간에 한 번" 을 요구하고 엔진이 따른다. 6단계부터는 Sieve vacation(RFC 5230)이 같은 일을 한다 — 간격은 엔진 기본값이다.
클라이언트: 설정 › 메일 › 부재중 자동 응답. 켜져 있으면 메일 화면의 메일함 패널 아래(사용량 위)에 "부재중 자동 응답 켜짐 · 11월 3일까지"(누르면 설정)를 보인다 — 메일 화면에 들어올 때 한 번 받고, 시간이 지나면 다시 계산한다(끝나는 시각이 지나면 숨기고, 시작 전이면 "10월 30일 ~ 11월 3일 · 설정").

스팸 · 원문 — 4단계

스팸 신고 · 스팸 아님: PATCH /api/messages/{id} · PATCH /api/messages 의 isJunk — true 면 키워드 $junk 를 붙이고 $notjunk 를 뗀다, false 면 반대(RFC 8621 4.1.1). 화면은 이동과 함께 보낸다 — 스팸 신고 { mailboxId: <스팸메일함>, isJunk: true }, 스팸 아님 { mailboxId: <받은편지함>, isJunk: false }. 엔진의 스팸 학습에 쓰이는지는 엔진 몫이다. 「되돌리기」는 원래 메일함으로 옮기며 보낸 값의 반대를 보낸다 — 표시를 지우는 값은 두지 않아서, 원래 아무 표시도 없던 메일도 되돌린 뒤에는 $notjunk(스팸 아님)가 남는다.
원문 내려받기: GET /api/messages/{id}/source — 엔진의 원본(blob)을 그대로 흘려보낸다(message/rfc822, Cache-Control: private, no-store). 파일 이름은 제목(없으면 "메일")에 .eml — 다운로드 헤더는 첨부와 같은 규칙(shared/utils/content-disposition.ts). 화면은 첨부 내려받기처럼 이동 전에 세션을 확인한다(confirmSession()).

실시간 알림 (`GET /api/mail-events`) — 5단계

서버가 메일 엔진(Stalwart)의 JMAP EventSource(RFC 8620 7.3)를 직원마다 하나 열고, 그 소식을 브라우저에 SSE(text/event-stream)로 흘려보낸다. 표준 응답 래퍼는 없다.

event: state
data: {"state":"<GET /api/mail-state 의 state 와 같은 값>","inboxUnread":3}

event: new-mail
data: {"count":2,"messages":[{"id":"…","from":{"name":"박서준","email":"seojun.park@arasystem.it.kr"},"subject":"…","receivedAt":"2026-10-28T05:42:00.000Z"}]}

event: ping
data: {"upstream":true}

event: end
data: {"reason":"token-expiring"}

이벤트	언제 · 뜻
`state`	연결 직후 한 번, 그 뒤 메일함 · 메일이 바뀔 때마다(엔진 신호를 0.3초 모아서). `state` 는 `GET /api/mail-state` 와 같은 값, `inboxUnread` 는 받은편지함의 안 읽은 수
`new-mail`	받은편지함에 새로 배달된 메일이 있을 때 — `$draft` 아님 · `$seen` 아님 · 보낸 사람이 나 아님. 새것부터 최대 5통(`count` 는 전체 수). 같은 변화의 `state` 다음에 온다
`ping`	25초마다(직원마다 한 간격 — 새 연결의 첫 ping 은 더 빨리 올 수 있다), 그리고 `upstream` 이 바뀌면 그때 바로. `upstream: false` 면 서버와 엔진 사이가 끊겨 다시 잇는 중이다 — 그동안 클라이언트는 1분 확인으로 돌아간다. 다시 잇는 중에 새로 연결하면 마지막으로 알던 `state` 와 `ping {upstream:false}` 가 바로 온다
`end`	서버가 곧 닫는다 — `token-expiring`(액세스 토큰이 끝나기 30초 전 — 남은 시간이 30초 이하인 토큰(세션이 끝나기 30초 안에 갱신한 토큰)이면 토큰이 실제로 끝날 때) · `server-shutdown`(서버 종료 · 재시작)

연결 전 실패 (표준 실패 형식 JSON)	코드
로그인 안 됨 · 토큰 만료	401 `AUTH_001`
한 직원의 연결이 5개를 넘음(브라우저마다 하나라 기기 · 브라우저 5개) · 요청 수 한도(경로마다 IP 당) · 엔진 한도	429 `REQ_001`
엔진에 연결할 수 없음(처음 연결 10초 상한) · 기다리는 사이 엔진 연결이 끝남 · 서버 종료 중	503 `MAIL_001`

스트림이 열린 뒤 계정을 더 쓸 수 없게 되면(엔진이 대리 접근을 거절) end 없이 닫는다 — 클라이언트는 끊김으로 보고 다시 이어 401 → 갱신 실패 → 세션 만료로 간다.

서버: 직원마다 엔진 연결 하나를 그 직원의 모든 연결에 나눠 쓴다(마지막 연결이 닫히고 30초 뒤 닫는다 — 새로 고침에 다시 열지 않게). 엔진 연결은 대리 접근 자격 · types=Mailbox,Email · ping=30 이다 — 엔진은 30초보다 짧게 주지 않는다(10초를 달라고 해도 30초, 2026-10-28 확인). 75초 동안 아무것도 오지 않으면 끊긴 것으로 보고 다시 잇는다(1 · 2 · 5 · 10 · 30초 간격에 ±20% — 엔진이 다시 뜰 때 모든 직원이 같은 순간에 붙지 않게). 그동안 클라이언트에는 ping 의 upstream: false 로 알린다. 같은 기준으로 이어서 3번 묻지 못하면 기준을 버리고 처음 상태로 다시 잡는다(그 차례는 new-mail 없이 — 엔진 한도 · 엔진이 내려간 동안은 세지 않는다). 엔진이 묻기를 한도(429)로 막으면 엔진 연결은 두고 5초(±20%) 뒤 다시 묻는다(upstream 은 true 그대로 — 다시 잇는 중이면 다시 잇기 간격대로). 5분 안전판: 엔진 신호가 없어도 마지막으로 물은 지 5분이 지나면 한 번 묻고, 달라졌으면 state(와 new-mail)를 보낸다 — 연결이 살아 있는 동안 클라이언트는 1분 확인을 멈추므로, 엔진이 신호를 빠뜨려도 낡은 값이 5분 넘게 남지 않게.
새 메일 판단: 엔진의 Email/changes(지난 state 부터 생긴 메일) → Email/get 으로 한다. 엔진의 EmailDelivery 신호는 초안을 만들어도 바뀌므로 쓰지 않는다(2026-10-28 확인). 배달에서 신호까지 0.5초 남짓이다(같은 날 개발 엔진). 다음 경우에는 new-mail 없이 state 만 보내고 기준을 다시 잡는다: 바뀐 것을 셀 수 없음(cannotCalculateChanges), 엔진이 옛 기준을 거부함(Stalwart 0.16.27 은 해석하지 못하는 sinceState 에 HTTP 400 notRequest 로 요청 전체를 거부한다 — 2026-10-28 확인), 한 번에 2,000건(500 × 4) 넘게 바뀜. Email/changes 의 생성은 "배달"이 아니라 "만들어짐"이다 — 받은 시각(receivedAt)이 변화를 본 때보다 10분 넘게 앞선 메일은 알리지 않는다 (메일 프로그램의 올리기 · mailcow 에서 옮길 때의 IMAP 가져오기(imapsync)가 옛 메일을 넣어도 알림이 쏟아지지 않게). 받은 시각을 읽지 못한 메일도 빼고, 엔진 시계가 앞서 미래 시각인 메일은 넣는다. 그래서 서버와 엔진 사이가 10분 넘게 끊겼다 다시 이으면, 그동안 온 메일은 state 로만 알린다(목록에는 나타나고 바탕화면 알림은 없다). "보낸 사람이 나"는 토큰의 주소와 발신 ID(별칭) 주소로 본다(대소문자 무시).
오래 열린 엔진 연결은 엔진의 동시 요청 한도(4)를 잡아먹지 않는다 — 한 직원의 스트림 8개를 연 채 그 직원 · 다른 직원의 보통 요청과 동시 요청 6개가 모두 됐다(2026-10-28 확인).
연결은 액세스 토큰이 끝날 때 닫는다(최대 1시간 — 그 전에 end). 로그아웃 · 비밀번호 변경으로 세션을 끊어도 다른 API 처럼 액세스 토큰이 끝날 때까지는 이어진다(1절 세션 규칙). 서버가 종료될 때는 열린 연결을 end 로 먼저 닫는다 — 오래 열린 연결이 종료를 붙잡지 않게. 알려진 한계: 잠자기 · VPN 재연결 · 망 바꿈으로 반쯤 열린 연결은 서버가 ping 을 쓰다 실패할 때(OS 기본 15분 안팎)까지 자리를 잡는다 — 그사이 그 직원의 연결이 5개에 닿으면 새 연결은 429 이고 화면은 1분 확인으로 이어진다.
응답 머리글: Content-Type: text/event-stream, Cache-Control: no-cache, no-transform, X-Accel-Buffering: no. 서버는 스트림을 열기로 정하면 머리글을 바로 보낸다. 앞단 nginx 는 이 경로만 버퍼링 · 캐시 · 압축을 끄고, 읽기 사이 시간 제한을 90초로 둔다(응답 전체가 아니라 두 번 읽는 사이 — ping 25초 · 클라이언트 감시 75초보다 길게, 머리글이 오지 않으면 90초에 504). 외부 리버스 프록시도 버퍼링을 끄고, 응답 전체 시간에 상한이 있으면 1시간 넘게 둔다(운영 확인 항목 — docker 스킬). 앱 로그에는 열고 닫는 것을 남기지 않는다(반복되는 정상 흐름) — 엔진 연결이 이어서 실패하면 warn. nginx 접근 로그에는 연결이 끝날 때 한 줄이 남는다(rt= 가 이어진 시간).
클라이언트
- 브라우저마다 연결 하나 — 탭이 여러 개면 한 탭만 연결하고(Web Locks) 다른 탭에 소식을 나눈다(BroadcastChannel). 탭마다 열면 HTTP/1.1 의 주소당 연결 6개를 금방 다 쓴다. 연결한 탭을 닫으면 다른 탭이 이어받는다. Web Locks 가 없는 브라우저는 실시간 없이 1분 확인만 한다. 연결은 로그인한 동안 앱 전체에서 유지한다(설정 등 메일 밖 화면에서도 바탕화면 알림 · 연결 상태가 이어지게). 목록 맞추기 · 1분 확인 멈춤은 메일 화면이 있을 때만 한다.
- fetch 로 읽는다 — 브라우저의 EventSource 는 401 을 알 수 없어 세션을 갱신할 수 없다. 401 이면 세션을 한 번 갱신하고 다시 잇는다(갱신도 실패하면 지금의 세션 만료 흐름).
- 연결이 살아 있는 동안(75초 안에 ping · state 가 오고 upstream: true)은 1분 확인을 멈춘다. 75초는 요청을 시작한 때부터 센다(머리글이 오지 않는 연결도 끊게). 끊기면(읽기 오류 포함 — 서버의 end 가 아닌 끝) 1분 확인으로 돌아가고 2 · 5 · 15 · 30 · 60초 간격으로 다시 잇는다. 연결이 자리 잡으면(첫 state 뒤 upstream: true 인 ping 이 오거나 20초가 지나면) 처음 간격부터 다시 센다. 자리 잡은 연결의 end 는 바로 다시 잇는다 (token-expiring 은 세션을 갱신한 뒤, server-shutdown 은 0~3초 흔들어 — 배포 때 모든 브라우저가 같은 순간에 붙지 않게). 그동안은 끊김으로 보지 않는다. 자리 잡기 전에 온 end 는 까닭과 상관없이 실패처럼 간격을 둔다 — 열리자마자 끝나는 연결(세션 끝 직전의 짧은 토큰 · 응답을 짧게 끊는 프록시)에서 갱신 · 다시 잇기를 왕복 시간 속도로 되풀이하지 않게(갱신 한도는 IP 마다라 같은 사무실 직원까지 막는다). 다시 잇는 간격의 흔들림은 ±20%.
- 세션을 갱신한 바로 뒤의 다시 잇기가 또 401 이면 세션 만료로 본다(axios 의 401 재시도와 같다 — 그 시도가 다른 까닭으로 끝나면 이 표시는 지운다). 갱신이 장애(5xx · 네트워크)로 실패하면 위 간격으로 기다렸다 다시 갱신해 본다. 한 이벤트가 1MB 를 넘으면 실패로 끊는다.
- 연결한 탭이 그만둘 때(닫힘 · 로그아웃 · pagehide)와 잠금을 이어받은 탭이 연결하기 전에 다른 탭에 끊김을 알린다 — 이어받은 탭의 연결이 열릴 때까지 모든 탭이 1분 확인으로 돌아간다 (탭 닫기 · 탭 폐기처럼 그만두는 탭이 알리지 못한 경우도 덮는다). 살아 있던 연결이 끊기면 1분 확인이 바로 한 번 묻고, 그 뒤 60초마다 묻는다.
- state 가 바뀌면 보이는 탭은 지금의 1분 확인이 하는 일(개수 · 보이는 목록 맞추기)을 그대로 하고, 숨은 탭은 inboxUnread 로 탭 제목만 맞춘 뒤 다시 보일 때 맞춘다. 실시간이 부른 맞추기는 1초 모아서 한 번 한다(한 통을 읽어도 state 가 바뀐다 — 연달은 바뀜에 목록을 여러 번 받지 않게).
- 바탕화면 알림(설정 › 메일 › 알림 — 브라우저 · 사용자마다 localStorage): 켜져 있고 브라우저가 허락했을 때, new-mail 을 받았는데 웹메일을 보고 있는 탭(보이고 초점이 있는 탭 — visibilityState === 'visible' && document.hasFocus())이 하나도 없으면 알린다. 두 번째 모니터에 웹메일을 띄워 두고 다른 창에서 일할 때도 알린다("다른 창을 보는 동안에도"). 한 통이면 제목 = 보낸 사람(이름, 없으면 주소) · 내용 = 메일 제목(「메일 제목도 보이기」를 끄면 "새 메일이 왔습니다"), 여러 통이면 "새 메일 N통" · "박서준 · 이도윤 외 1명". 같은 tag 로 앞 알림을 바꿔 쓴다(쌓이지 않는다). 누르면 그 탭으로 와서 메일을 연다(여러 통이면 받은편지함). 사용자가 웹메일로 돌아오면(어느 탭이든 보이고 초점이 생기면) 띄운 알림을 닫는다. 허락은 사용자가 누른 뒤에만 묻는다(목록 위 한 번 권하기 · 설정의 켜기 칸). new Notification() 을 막는 브라우저(휴대폰 Chrome)는 처음 실패할 때 "지원하지 않음"으로 바꾼다.

메일 필터 (`/api/mail-filters`) — 6단계

interface MailFilterSet {
  rules: MailFilterRule[]     // 위에서부터 차례로 적용한다 — 50개까지
  version: string             // 지금 규칙의 지문 — 해석하지 말고 PUT 에 그대로 돌려보낸다(그사이 다른 곳에서 규칙이 바뀌었으면 409 MAIL_012). 영문 · 숫자 · - · _ 128자까지. 규칙만 본다(부재중이 바뀌어도 그대로)
  isActive: boolean           // false = 우리 규칙이 엔진에서 꺼져 있거나(다른 규칙이 켜짐) 저장해 둔 원본을 읽을 수 없어 지금은 필터 · 부재중 응답이 동작하지 않는다(드묾) — 저장하면 다시 켜진다
                              // (아래 "저장 자리"의 새 판 원본은 예외). 한 번도 저장하지 않은 계정은 true(막힌 것이 없다)
}
interface MailFilterRule {
  id: string                  // 클라이언트가 만든다(UUID — 영문 · 숫자 · - · _ 64자까지) — 목록 안에서 겹치지 않게
  name: string                // 0~50자(앞뒤 공백은 지워 저장한다), 제어 문자는 안 된다 — 비면 화면이 조건으로 이름을 보인다
  isEnabled: boolean
  match: 'all' | 'any' | 'always'     // 조건이 모두 맞음 · 하나라도 맞음 · 모든 메일(조건 없음)
  conditions: MailFilterCondition[]   // all · any 는 1~5개, always 는 빈 배열
  actions: MailFilterActions          // 하나 이상
}
interface MailFilterCondition {
  field: 'from' | 'to' | 'subject' | 'body'  // 보낸 사람(이름 · 주소) · 받는 사람(받는 사람 · 참조의 이름 · 주소) · 제목 · 본문(글자 부분)
  operator: 'contains' | 'notContains'
  value: string               // 1~200자(앞뒤 공백을 지운 값 — 그 값으로 저장한다), 제어 문자 · `${` 는 안 된다
}
interface MailFilterActions {
  moveToMailboxId: string | null  // 받은편지함 · 내 메일함 · 보관함 · 스팸메일함 · 휴지통 (보낸편지함 · 임시보관함은 400 VAL_001). 없는 id 도 받는다 — 지운 메일함을 가리키는 규칙이 남아 있을 수 있다
  markAsRead: boolean
  flag: boolean
  forwardTo: string | null        // 사내 주소(도메인이 `MAIL_DOMAIN` 과 똑같은 주소 — 하위 도메인은 안 된다)만, 자기 주소는 안 된다(대소문자 무시).
                                  // 앞뒤 공백은 지워 저장한다. `${` 는 안 된다
}

PUT 본문은 { rules, version } 뿐이다 — isActive 같은 다른 키를 보내면 400 VAL_001(모르는 필드). 응답은 저장한 규칙(앞뒤 공백을 지운 값)과 새 version 이다.
적용 순서 — 새로 온 메일을 위의 규칙부터 차례로 견주고, 맞는 규칙의 할 일을 모두 한다(읽음 · 중요는 겹쳐 붙는다). 메일함으로 옮기는 규칙에 맞으면 거기서 멈춘다 — 아래 규칙은 보지 않는다. 받은편지함으로 옮기는 규칙을 위에 두면 "늘 받은편지함에"가 된다. 전달은 한 통에 한 곳 — 엔진 한도(사용자 스크립트의 리다이렉트 1)라 두 번째 전달은 엔진이 조용히 버린다(2026-10-28 확인). 사본은 늘 남긴다(redirect :copy). 스팸으로 판정된 메일에는 아무 규칙도 적용하지 않는다(부재중 응답도 하지 않는다) — 엔진은 규칙의 옮기기가 스팸메일함 분류를 이기므로(같은 날 확인) 막는다. 판정은 엔진의 분류 그대로다(지금 엔진 설정은 5점부터 스팸 — 아래 "만드는 Sieve"의 스팸 막기). 꺼 둔 규칙은 목록에만 있고 적용하지 않는다. 이미 받은 메일에는 저절로 적용하지 않는다 — 저장할 때 고르면 아래 "이미 받은 메일에 적용"(7단계).
저장 자리 — 엔진의 Sieve 스크립트 하나(arasystem)에 필터와 부재중 자동 응답을 함께 둔다. Stalwart 0.16.27 은 계정마다 켜진 스크립트가 하나뿐이고 엔진의 VacationResponse 도 스크립트(vacation)라서, 부재중을 켜면 필터가 꺼지고 필터를 켜면 부재중이 꺼진다(같은 날 확인).
- 4단계 /api/mail-vacation 은 계약 그대로 두고 저장 자리만 이 스크립트로 옮긴다 — 엔진의 VacationResponse 는 더 쓰지 않는다. 스크립트가 아직 없는 계정은 처음 읽을 때 VacationResponse 의 값을 가져온다(개발 데이터 이어받기). 엔진의 vacation 스크립트는 고칠 수 없다(엔진이 forbidden).
- 스크립트 머리의 주석에 규칙 · 부재중 원본(JSON — 판 번호 v 를 함께 둔다)을 두고, 읽을 때는 그것만 믿는다(엔진의 Sieve 를 다시 해석하지 않는다).
  - 스크립트가 아직 없으면 빈 규칙 + isActive: true, 부재중은 엔진의 VacationResponse 값(위 이어받기).
  - 스크립트는 있는데 원본이 없거나 깨졌으면 빈 규칙 + isActive: false, 부재중은 꺼짐 — 저장하면(필터든 부재중이든) 덮어쓴다.
  - 원본의 판이 이 서버가 아는 것보다 새로우면(새 서버를 배포했다 되돌린 경우) 읽기는 위와 같지만 쓰기는 거절한다(503 MAIL_001) — 옛 서버가 새 판의 규칙을 지우지 않게.
- 쓸 때는 읽은 상태 그대로일 때만(ifInState) 쓰고 켠다(onSuccessActivateScript). 그사이 바뀌면 다시 읽어 확인한다 (쓰기 3번까지 — 시도마다 읽는 사이 글이 사라지면 그 읽기도 3번까지 다시 한다. 그래도 어긋나면 503 MAIL_001). 필터 저장은 다시 읽은 규칙의 지문이 version 과 다르면 409 MAIL_012(부재중 응답만 바뀐 것은 걸리지 않는다). 부재중 저장은 규칙을 그대로 두고 부재중 부분만 바꾼다. 다만 저장해 둔 규칙이 보내는 규칙과 이미 같으면 지문이 달라도 200 으로 저장한다 — 결과를 모르는 실패 뒤에 같은 요청을 다시 보낸 경우가 409 로 끝나지 않게 (꺼져 있었으면 이때 다시 켜진다).
만드는 Sieve (엔진 확인 사실 — 2026-10-28):
- 조건: from → header :contains "from", to → header :contains ["to", "cc"], subject → header :contains "subject", body → body :text :contains. 한국어 제목(인코딩된 머리글) · 본문 · 표시 이름 모두 맞는다. 대소문자는 ASCII 만 무시한다(엔진 기본 비교 — i;unicode-casemap 은 없다).
- 한 규칙은 if 하나: 표시(addflag — 옮기기보다 먼저, 엔진은 옮기는 순간의 표시만 붙인다) → 전달 → 옮기기(fileinto :mailboxid "<id>" "INBOX" + stop). 옮길 메일함이 없으면 대체 이름 "INBOX" 로 받은편지함에 들어온다.
- 스팸 막기는 엔진의 분류 표시로 한다 — X-Spam-Score 머리글(spam, score=9.70 · ham, score=2.20)이 spam 으로 시작하면 아무 규칙도 · 부재중도 하지 않는다 (header :matches "X-Spam-Score" "spam*"). 엔진이 우리 스크립트를 돌리기 전에 붙인다. X-Spam-Status: Yes|No 는 스크립트가 끝난 뒤 실제로 들어간 곳에 따라 붙어 쓸 수 없다 (우리 규칙이 옮긴 스팸은 "No" 였다). 엔진 설정의 기준 점수(scoreSpam — 지금 5)를 바꿔도 이 표시가 따라간다.
  - spamtest 는 쓰지 않는다 — 엔진의 값은 "스팸이면 10"이 아니라 점수를 정수로 내린 값(10에서 멈춤)이라, 10 으로 막으면 5~10점 스팸을 놓친다 (2026-10-28 실엔진: 2.20점 → 2, 9.70점 → 10 미만, 11.2점 → 10. 처음 구현은 10 으로 막아 9.70점 스팸을 규칙대로 옮기고 부재중 응답까지 보냈다).
  - 바깥에서 같은 이름의 머리글을 넣어 와도 엔진의 머리글이 함께 남는다(하나라도 맞으면 참). 그래서 위조로 스팸을 숨길 수는 없고, 자기 메일에 규칙이 적용되지 않게만 할 수 있다 (그 메일은 엔진 판정대로 들어간다). 엔진의 스팸 필터는 바깥에서 오는(인증 없는) 메일에만 돌아 사내 메일에는 이 머리글이 없다 — 규칙이 그대로 적용된다.
- 부재중: 엔진이 하던 대로 vacation :mime(본문 base64) — 제목은 RFC 2047 로 인코딩해 넣는다. Stalwart 는 require 와 상관없이 문자열의 ${…} 를 늘 변수로 펼쳐서 그대로 넣으면 지워진다(같은 날 확인). 기간은 currentdate :zone "+0000"(엔진 시간대에 기대지 않게 — 같은 날 확인). 같은 사람에게 다시 답하는 간격은 엔진 기본값(지금과 같다).
- 규칙 값에 ${ 는 받지 않는다(400 VAL_001) — 펼쳐져 빈 값이 되면 :contains 가 모든 메일에 맞는다. 문자열은 " · \ 를 이스케이프한다. %{…}(Stalwart 의 식 모양)는 펼치지 않아 막지 않는다 — %{"a"} · %{} · %{1+1} · %{subject} 모두 글자 그대로 견주었다(같은 날 확인).
- 크기: 엔진 한도는 스크립트 102,400바이트 · 문자열 4,096바이트다. 만든 스크립트가 90,000바이트를 넘으면 저장하지 않고 400 MAIL_013.
로그 — 규칙의 글(조건 값 · 전달 주소)은 남기지 않는다(검색어처럼 직원의 내용이다). 규칙 수 · 크기 · 결과만. 엔진이 스크립트를 거절하면(invalidScript → 500 SYS_001) 엔진 설명의 줄 · 칸만 남긴다 — 설명 문장에는 만난 문자열(규칙의 글)이 그대로 들어갈 수 있다.
클라이언트: 설정 › 메일 › 필터(/settings/mail/filters, 탭 제목 "메일 필터") — 메뉴는 서명 · 부재중 자동 응답 · 필터 · 알림.
- 켜기 · 끄기 · 순서 바꾸기 · 지우기 · 고치기 모두 PUT 전체 교체(받은 version 으로). 켜기 · 순서는 화면을 먼저 바꾸고 실패하면 되돌린다(오류 알림). 지우기는 확인 없이 하고 알림의 되돌리기로 지운 필터를 지운 자리에 다시 넣어 저장한다 — 그사이 바꾼 다른 필터(켜기 · 순서 등)는 그대로 둔다. 저장은 한 번에 하나다 — 앞 저장이 도는 동안 누른 [되돌리기]는 차례로 보낸다. 고치기 창의 [저장]이 끝나면 "필터를 저장했습니다."
- MAIL_012 — 목록 위 줄 "다른 곳에서 필터가 바뀌어 저장하지 않았습니다. 다시 불러온 뒤 고쳐 주세요." + [다시 불러오기]. 고치던 창은 닫지 않는다 — 창 안에도 같은 안내와 [다시 불러오기]를 둔다(모달이라 뒤의 줄을 누를 수 없다). 창에서 다시 불러오면 쓴 내용은 그대로이고, 다음 [저장]은 다시 받은 목록에 그 필터를 넣는다(같은 id 자리 — 그사이 다른 곳에서 지워졌으면 맨 아래).
- isActive: false — 목록 위 줄 "지금은 필터와 부재중 자동 응답이 동작하지 않습니다…" + [다시 켜기](지금 목록 그대로 저장).
- 읽기 화면 ⋯ 「이런 메일로 필터 만들기」 → /settings/mail/filters?from=<보낸 사람 주소> — 새 필터 창이 "보낸 사람 · 포함 · 그 주소"로 채워져 열린다(초점은 할 일의 첫 칸). 50개를 다 만들었는지 알려고 ⋯ 메뉴를 열 때 GET 을 한다(받아 둔 목록이 없거나 50개일 때만 — 알림 없이).
- 검사는 서버와 같은 규칙(이름 50 · 값 200 · 조건 5 · 규칙 50 · ${ · 제어 문자 · 할 일 하나 이상 · 전달은 사내 주소이고 자기 주소 아님) — 칸 아래에만 알린다. 전달 주소의 앞부분은 서버(IsEmail)보다 좁게 본다(RFC 5322 dot-atom · 64자) — 화면이 통과시킨 주소를 서버가 거절하지 않게. 규칙이 50개면 [새 필터] · 「이런 메일로 필터 만들기」를 끄고 까닭을 보인다. 지운 메일함을 가리키는 규칙은 목록에 빨간 안내.
이 단계에서 하지 않는 것: 바깥 주소로 전달 — 전달한 메일은 보낸 사람(From)이 원래의 바깥 도메인인데 우리 서버가 건넨다. 엔진은 봉투 보낸 사람을 필터 주인으로 바꿔 SPF 는 통과하지만(SRS 는 없다 — 거절되면 반송은 원래 보낸 사람이 아니라 필터 주인에게 온다), 받는 쪽의 DMARC 는 From 기준이라 원래 보낸 쪽의 DKIM 서명에 기댄다. 서명이 없거나 깨진 메일은 그 도메인이 엄격하면(p=reject) Gmail 등이 거절하거나 스팸으로 보낸다 — 전달 메일의 일반적인 한계라 SRS 가 있어도 같다. 그리고 회사 메일이 개인 메일로 자동으로 빠지는 통로다 — 회사 정책으로 허용하지 않는다(2026-10-29 결정 — 전달은 사내 주소로만). 보통 발송(직원이 바깥 주소로 보내는 메일)과는 상관없다. 크기 · 첨부 · 날짜 조건, 정규식, 맞는 메일 미리 보기, mailcow(SOGo)의 필터 옮겨 오기(운영 전환 때 — imapsync 로는 옮겨지지 않는다).

이미 받은 메일에 적용 (`/api/mail-filter-runs`) — 7단계

필터를 저장할 때 고르면(고치기 창 「받은편지함에 이미 있는 메일에도 적용」) 받은편지함에 이미 있는 메일에도 그 규칙 하나를 적용한다. 엔진의 Sieve 는 메일을 받을 때만 돌기 때문에 서버가 받은편지함을 읽어 같은 규칙으로 판정하고 표시 · 옮기기를 한다.

interface MailFilterRunRequest {
  match: 'all' | 'any' | 'always'          // 필터 규칙과 같은 검사(MailFilterRule 의 match · conditions)
  conditions: MailFilterCondition[]         // all · any 는 1~5개, always 는 빈 배열
  actions: {                                // 하나 이상 — 전달은 없다(이미 받은 메일은 전달하지 않는다)
    moveToMailboxId: string | null          // 필터 규칙과 같은 메일함만(보낸편지함 · 임시보관함은 400). 받은편지함이거나 없는 메일함이면 옮기지 않는다
    markAsRead: boolean
    flag: boolean
  }
  cursor: string | null                     // 처음은 null, 이어 할 때는 앞 응답의 cursor 그대로(해석하지 않는다)
}
interface MailFilterRun {
  scanned: number          // 이번 요청에서 확인한 받은편지함 메일 수
  matched: number          // 그중 조건에 맞아 할 일을 한 메일 수(이미 읽음 · 중요였던 메일도 센다)
  remaining: number        // 아직 확인하지 않은 메일 수 — 어림(그사이 들어오고 나간 메일이 있다)
  cursor: string | null    // null = 끝. 아니면 같은 본문에 이 cursor 를 넣어 다시 보낸다
}

받은편지함만, 받은 시각이 최근인 메일부터 본다. 저장해 둔 필터를 읽지 않고 본문의 규칙을 쓴다(클라이언트는 방금 저장한 그 규칙을 보낸다) — 그래서 적용하는 동안 다른 필터를 켜고 끄거나 저장해도 멈추지 않는다.
한 요청은 25초 안에 끝내고 cursor 를 돌려준다 — 4단계 "오래 걸리는 처리"와 같은 상한 · 같은 규칙(다음 차례는 남은 시간이 5초보다 많을 때만, 엔진 호출마다 남은 시간만큼, 진행한 것이 있으면 거기까지 200, 하나도 확인하지 못했으면 503 MAIL_001). 같은 직원의 적용은 한 번에 하나 — 진행 중이면 엔진에 묻지 않고 429 REQ_001(다른 탭 · PC).
판정은 서버가 한다 — 새로 오는 메일의 Sieve(위 "메일 필터"의 "만드는 Sieve")와 같은 규칙을 따라 한다. 엔진 검색(Email/query 의 글자 조건)은 쓰지 않는다 — 낱말이 통째로 같을 때만 맞고('회의'로 '회의를' · '아라'로 '김아라'를 못 찾는다) header 조건은 아무것도 찾지 못한다(Stalwart 0.16.27, 2026-10-28 확인).
- 보낸 사람: From 머리글의 원래 글 — 접힌 줄(줄바꿈 + 공백 · 탭)은 띄어쓰기 하나로 펴고(접지 않은 탭 · 이어진 공백은 그대로), 인코딩된 글(RFC 2047 — 문자셋 그대로)은 홀로 선 것만 풀고(앞이 처음 · 공백 · " · ,, 뒤가 끝 · 공백 · " — abc=?…?= · =?…?=<a@b> · (=?…?=) 는 그대로. 공백만 사이에 둔 인코딩된 글끼리는 붙인다), 앞뒤 공백을 뺀 것 — 따옴표 · 꺾쇠까지 견준다("Kim, Ara" <kim@…> 에 "Kim 이 맞는다 — 엔진과 같다). 받는 사람: To · Cc 머리글 각각(하나라도 맞으면). 제목: 풀어 쓴 제목.
- 본문: 텍스트 · HTML 부분과 텍스트 첨부(text/* — 파일로 붙인 것도. 엔진이 그렇게 본다). 한 부분은 앞 256KiB 까지, 한 통은 모두 합쳐 1MiB 까지 본다 (글자 부분이 많아 넘으면 부분마다 같은 몫만큼 앞쪽만 — 바깥에서 온 메일 한 통으로 서버가 메모리를 크게 쓰지 않게). HTML 은 글자 부분만 — 엔진과 같게:
  - 태그는 < 부터 다음 > 까지다 — < 뒤가 무엇이든 태그이고(a < b · <광고> 도), 따옴표 안의 > 에서도 끝난다. 닫히지 않은 < 는 끝까지 삼킨다. 태그는 속성까지 빈자리 없이 뺀다(회<b>의</b>록 → "회의록", div · li · h1 · 표 칸 · 표 줄 · hr · 여는 p 사이도 이어 붙는다). 주석()은 안의 글까지 뺀다
  - </p>(닫는 것만) · <br>(<br/> · <br /> · </br> · 대문자도)은 줄바꿈이다 — 찾을 글(줄바꿈이 없다)은 이 자리를 건너 맞지 않는다(<p>앞</p><p>뒤</p> 에 "앞뒤" · "앞 뒤" 모두 안 맞음)
  - <style> · <script> · <head> · <template> 은 안의 글까지 뺀다(<title> · <noscript> 등은 글이 남는다). 그 안의 </p> · <br> 도 줄바꿈이다
  - 태그 이름 뒤에 속성이 붙으면 엔진은 그 태그를 알아보지 못한다 — <br clear="all"> 은 줄바꿈이 아니고 <style type="text/css"> · <head lang="ko"> 는 안의 글이 남는다. 서버도 그렇게 본다
  - 원문의 이어진 공백(띄어쓰기 · 탭 · 줄바꿈)은 태그를 건너서도 띄어쓰기 하나. 문자 참조를 푼다(이름 · 10진 · 16진 — ; 로 끝나는 것만,   는 U+00A0) — 푼 글자는 줄이지 않고 그대로 넣는다(   는 띄어쓰기 둘, 
     은 줄바꿈)
- 대소문자는 ASCII 만 무시한다. "포함하지 않음"은 그 머리글 · 본문 부분이 없을 때도 참이다(엔진과 같다).
- 확인(2026-10-29): 실배달 20통 — 본문 14가지(HTML 만 · 속성 · style · 문자 참조 · 대안 두 쪽 · 텍스트 첨부 · 주석 · script · 인라인 부분 · QP · EUC-KR ·   · 블록 사이)와 머리글 6가지(따옴표 이름 · 받는 사람 여럿 · 인코딩된 참조 · 인코딩된 제목 · EUC-KR 제목), 인증 발송 25통 — HTML 글자 뽑기(인라인 태그 · 원문 줄바꿈 · 공백 겹침 · p · br · div · li · h1 · 표 · blockquote · hr · title · 숫자 참조 · 대문자 태그 등), 인증 발송 69통 — 속성이 붙은 태그 · 글을 빼는 태그(head · template 등) · 글자 그대로의 < · 따옴표 안 > · 참조로 쓴 공백 · 머리글의 접힌 줄 · 인코딩된 글의 경계에서 엔진과 같은 판정이 되게 맞췄다(스팸으로 분류된 1통은 판정 불가).
- 알려진 한계(드묾): 첨부한 메일(.eml) 안, 256KiB · 1MiB 를 넘는 뒤쪽, HTML5 에만 있는 이름 참조(&period; · 대문자 &AMP; 등 — 엔진은 푼다)는 엔진과 다를 수 있다.
- 스팸 판정 표시는 보지 않는다 — 받은편지함에 있는 메일은 사용자가 이미 본 메일이다("스팸 아님"으로 되돌린 메일 포함).
할 일: 읽음 · 중요 표시를 붙이고, 옮기기는 받은편지함에서 빼고 그 메일함에 넣는다(맞은 메일을 차례마다 엔진 요청 한 번으로). 확인하는 사이 받은편지함에서 빠진 메일은 건너뛴다. 옮길 메일함이 없거나(지워짐) 받은편지함이면 옮기지 않고 표시만 한다. 영구 삭제는 하지 않는다(휴지통으로 옮기는 규칙도 옮기기다).
적용을 시작한 때 받은편지함에 있던 메일만 본다 — 첫 요청이 받은편지함의 가장 최근 받은 시각을 위 경계로 잡고(cursor 에 담는다) 그 뒤에 온 메일은 보지 않는다 (새로 온 메일은 Sieve 가 규칙 차례대로 이미 판정했다 — 한 규칙으로 다시 판정하면 위 규칙의 "멈춤"을 건너뛴다).
cursor 는 서버가 만든 글이다(위 경계 · 마지막으로 받은편지함에 남긴 메일과 그 받은 시각 · 규칙의 지문). 그 메일이 그사이 빠졌으면(다른 탭에서 옮김 등) 그 받은 시각의 메일부터 다시 읽는다 — 건너뛰지 않는다(그 초의 메일을 다시 판정해 맞은 수를 두 번 셀 수는 있다). 엔진은 받은 시각이 같은 메일을 늘 같은 차례로 준다(만든 차례 — 2026-10-29 확인). 다른 규칙의 cursor · 깨진 cursor 는 400 VAL_001.
엔진 한도: Email/query 는 한 번에 5,000통까지(queryMaxResults)라 차례마다 나눠 읽는다. 측정(개발 엔진, 2026-10-29, 시험 메일 5,000통): 보낸 사람 조건으로 4,500통을 확인하고 450통을 옮기는 데 1.3초, 본문 2,000통 읽기 1초 안팎 — 받은편지함 수만 통도 머리글 조건이면 한 요청, 본문 조건이면 몇 요청이다.
로그 — 규칙의 글은 남기지 않는다(필터와 같다). 확인 · 적용 수 · 차례 수 · 걸린 시간만.
클라이언트: 고치기 창의 「받은편지함에 이미 있는 메일에도 적용」 — 창을 열 때마다 꺼져 있다(필터의 설정이 아니다). PUT /api/mail-filters 가 성공한 뒤 저장한 그 규칙 (응답 목록의 같은 id — 앞뒤 공백을 지운 값)으로 이 요청을 cursor 가 null 이 될 때까지 보낸다.
- 칸을 끈다(칸 아래 설명이 까닭을 말한다): 이 탭에서 다른 적용이 진행 중, 그리고 이미 받은 메일에 할 일이 없는 필터 — 읽음 · 중요 표시가 없고 옮기기도 없거나 받은편지함으로 · 지워진 메일함으로 옮기는 것뿐(까닭 문구는 지워진 메일함 → 받은편지함 → 전달만 차례로 고른다). 서버는 그런 규칙도 받는다(맞은 수만 센다).
- 진행 알림 "‘{이름}’ 필터를 받은편지함에 적용하는 중 · {확인} / {전체}통 확인"(확인 = scanned 합, 전체 = 확인 + remaining) → 끝나면 그 자리에서 "‘{이름}’ 필터를 받은편지함의 메일 N통에 적용했습니다."(N = matched 합) + 옮기는 필터이고 1통 이상이면 [{메일함} 보기], 0통이면 "받은편지함에 ‘{이름}’ 필터에 맞는 메일이 없습니다."
- 멈춤: "‘{이름}’ 필터 — {전체}통 가운데 {확인}통까지 확인하고 멈췄습니다(N통에 적용). 다시 시도해 주세요." + [다시 시도](마지막 cursor 로 이어서). 처음 요청부터 실패하면 "필터는 저장했지만 받은편지함에 적용하지 못했습니다. 다시 시도해 주세요." + 다시 시도. 429 는 "다른 창에서 필터를 받은편지함에 적용하는 중입니다. 끝난 뒤 다시 시도해 주세요." — 도중의 429 면 다시 시도도 붙인다. 확인 0 인데 cursor 가 있는 응답이 세 번 이어지면 멈춘다(같은 요청을 끝없이 보내지 않게 — 멈춤 문구와 같다).
- 그동안 다른 화면으로 가도 이어 한다. 탭을 닫으면 멈춘다(이어 하지 않는다). 세션이 바뀌면(로그아웃 · 만료 · 다른 계정) 다음 요청을 보내지 않고 알림을 닫는다.
고치기 창의 나가기 확인(6단계 한계를 고친다): 창을 연 뒤 바꾼 것이 있으면 [취소] · Esc · 다른 화면으로 가기에 확인 — "저장하지 않은 필터가 있습니다" / "창을 닫으면 고친 내용이 사라집니다." [계속 고치기](처음 초점 · Esc) [닫기]. 다른 화면으로 갈 때는 "이 화면을 나가면 고친 내용이 사라집니다." [나가기]. 탭 닫기 · 새로고침은 브라우저 확인창. 읽기 화면에서 채워 연 새 필터는 채운 그대로면 묻지 않는다.

보내기 취소 · 예약 발송 (`POST /api/messages` 의 기다리기 · `/api/scheduled-messages`) — 9단계

메일 서버(엔진)가 제출을 잠시 붙잡았다가 보낸다 — EmailSubmission 의 FUTURERELEASE(envelope.mailFrom.parameters 의 HOLDFOR 초 · HOLDUNTIL 시각). 붙잡힌 동안은 undoStatus: pending 이고, 취소하면(canceled) 배달되지 않고, 시간이 되면 보낸다(final) — Stalwart 0.16.27, 2026-10-29 확인. 기다리는 곳이 서버라 창을 닫아도 보내진다. 화면은 디자인 README "9단계"(디자인 원본 MailSendLater).

interface PendingSend {
  sendAt: string               // 엔진이 보낼 시각(UTC)
  kind: 'undo' | 'scheduled'   // 보내기 취소를 기다리는 중 · 예약 발송
}

보내기 취소: sendAt 없이 보내면 서버가 그 직원의 설정(undoSendSeconds — 아래 "보내기 · 읽기 설정", 처음 10초)만큼 붙잡는다(HOLDFOR). 0 이면 지금처럼 바로 보낸다. 응답 pendingSend: { kind: 'undo', sendAt } — 클라이언트는 남은 시간을 이 시각으로 센다. 다만 PC 시계가 어긋나면 알림이 설정보다 오래 남으므로, 설정한 초를 알면 "지금 + 그 초 − 조금"을 넘기지 않는다(구현하며 정함 — 2026-10-29 리뷰).
예약 발송: 발송 본문의 sendAt(UTC) 까지 붙잡는다(HOLDUNTIL) — 지금부터 5분 뒤 이상 · 7일 안. 밖이면 400 VAL_001. sendAt 은 Z 로 끝나는 UTC 만 받고 소수 초는 버린다. null 은 없는 것과 같다(바로 보내거나 보내기 취소 설정대로). 엔진이 그 시각을 거절하면(forbiddenMailFrom — 엔진 한도가 바뀐 경우 등) 400 VAL_001 이고 만든 보낸 사본은 지운다(구현하며 정함). 7일은 엔진 한도다(x:MtaExtensions 의 futureRelease — 로그인 세션 7d. JMAP 능력의 maxDelayedSend 는 30일로 보이지만 엔진이 7일 넘게는 거절한다 — 2026-10-29 확인). 붙잡은 메일의 대기열 만료는 풀리는 시각 + 3일이라 7일 안은 안전하다(같은 날 확인). 예약에는 보내기 취소 시간을 더하지 않는다. 응답 pendingSend: { kind: 'scheduled', sendAt }.
받는 사람 확인은 제출 순간에 한다 — 붙잡아도 엔진이 사내 받는 사람을 그 자리에서 묻는다(없는 사내 주소는 곧바로 delivered: no · 550 5.1.2, 반송 없음 — 2026-10-29 확인). 그래서 위 "받는 사람별 결과"(일부 거절 rejectedRecipients · 모두 거절 MAIL_010 · MAIL_011)는 그대로다. 바깥 주소는 풀린 뒤 배달되고, 실패하면 지금처럼 반송 메일이 온다. 붙잡은 제출의 결과는 사내 · 바깥 모두 곧바로 250 2.1.5 Queued 다(거절된 사람만 delivered: no). 모두 거절인데 제출이 아직 기다리고 있으면(모두 4xx 등) 같은 요청에서 먼저 취소하고 사본을 지운다 — 풀리는 시각에 다시 보내지 않게(취소를 엔진이 받지 않아도 사본은 지우고 warn). 모두 5xx 면 엔진이 붙잡아도 곧바로 final 이라 지우기만 한다(같은 날 확인).
보낸 사본의 자리: 제출하면서 지금처럼 보낸편지함으로 옮긴다 — 보내기 전에도 보낸편지함에 보이고 pendingSend 로 "보내는 중" · "예약 · 시각"을 보인다. 예약은 사본에 내부 표시(키워드 $ara-scheduled — 목록 · 화면에는 표시로 내보내지 않는다. 보낸 뒤에도 남는다 — 해가 없다)를 붙여 보내기 취소를 기다리는 것과 가른다. pendingSend 는 엔진의 기다리는 제출(undoStatus: pending)이면서 보낼 시각이 아직 오지 않은 것에만 붙는다(구현하며 정함) — 붙잡지 않은 발송도 대기열에서 배달하는 동안 잠깐 pending 이고, 보낼 시각이 지나 배달 중인 메일은 null 이다(그때 취소하면 MAIL_014). 기다리는 제출은 보낼 시각으로 찾는다(EmailSubmission/query 의 filter.after: 지금 — 엔진의 색인을 탄다. undoStatus 조건은 모든 제출을 훑어 계정마다 65~140ms 라 쓰지 않는다). 차례는 보낼 시각 오름차순 — 엔진의 정렬 이름은 sentAt 이다(sendAt 은 unsupportedSort — 2026-10-29 확인). 한 번에 500개까지 읽고, 닿으면 warn 을 남긴다. 목록 · 상세 · 한 통 바꾸기 응답에 엔진 호출(찾기 · 읽기)이 붙고, 읽지 못하면 pendingSend: null 로 준다(표시만 — 옮기기 · 지우기를 막는 확인은 닫힌 쪽으로, 아래).
붙잡힌 메일은 취소로만 보낸편지함을 떠난다(구현하며 정함 — 2026-10-29 리뷰): 붙잡힌 메일을 옮기거나 지워도 엔진은 시간이 되면 보낸다(지운 메일도 나간다) — 우리 API 로는 그렇게 되지 않게 막는다.
- 한 통 PATCH /api/messages/{id} 의 mailboxId · isJunk 와 DELETE /api/messages/{id} 는 409 MAIL_015(아무것도 바꾸지 않는다), 여러 통 PATCH /api/messages 는 그 id 를 failedIds 로, POST /api/message-deletions 는 skippedIds 로. 읽음 · 중요 표시는 바꿀 수 있다.
- 메일함 지우기 · 비우기(4단계 "메일함 관리")는 붙잡힌 메일을 그대로 두고 나머지를 처리한다 — 붙잡힌 메일은 remaining 에 들고, 한 요청에서 처리한 것이 없으면(남은 것이 붙잡힌 메일뿐) 409 MAIL_015 로 끝난다(지우기는 메일함을 지우지 않는다). 우리 API 로는 붙잡힌 메일이 보낸편지함 밖에 있을 수 없어 IMAP 으로 옮긴 메일에서만 생긴다.
- 이미 받은 메일에 필터 적용(7단계)은 붙잡힌 메일을 옮기지 않고 표시만 한다(matched 에는 센다).
- 막을지 볼 때 엔진에 묻지 못하면(오류 · 시간) 바꾸지 않고 503 MAIL_001 이다 — 위의 모든 길이 닫힌 쪽으로 실패한다. 다 받았는지는 응답의 total(calculateTotal)로 정하고, 모르면 다 보지 못한 것으로 본다(2026-10-29 리뷰 2 — 요청한 limit 으로 정하지 않는다). 기다리는 제출을 찾는 조회가 500개에 닿으면 그 메일 id 로 다시 묻고(같은 "지금 뒤" 조건), 그것도 넘치면 MAIL_001. 보낼 시각을 읽지 못한 기다리는 제출도 붙잡힌 것으로 본다(화면 표시 pendingSend 는 그때 null).
- 알려진 한계: IMAP · 다른 JMAP 프로그램이 옮기거나 지우는 것은 막지 못한다 — 엔진은 그래도 시간이 되면 보낸다.
- 클라이언트는 붙잡힌 메일을 목록에서 고르지 못하게 하고(고르기 칸 aria-disabled + 까닭 — 모두 고르기 · 범위도 건너뛴다), 읽기 화면에는 옮기기 · 스팸 단추를 두지 않는다 — [삭제]는 확인(처음 초점 「취소」) 뒤 발송을 취소하고 휴지통으로 옮긴다(보내기 취소를 기다리는 메일도 같다). MAIL_015 는 인터셉터 알림(메일함 처리는 진행 알림도 거기서 멈춘다 — 4단계와 같은 결).
GET /api/scheduled-messages — 예약한 메일(kind: 'scheduled' 이고 아직 보내지 않은 것)을 보낼 시각 차례로. 화면은 pageInfo.total 로 메일함 패널의 「예약됨」(있을 때만)을 보인다 — 메일 화면에 들어올 때 · 보내거나 취소한 뒤 · 새 메일 확인(3단계) · 실시간 알림(5단계)이 바뀜을 알릴 때 다시 묻는다. 보낸 메일은 저절로 빠진다(엔진의 제출이 final). 엔진이 풀어도 새 메일 확인 · 실시간 알림의 상태(메일함 · 메일)는 바뀌지 않는다 — 그래서 화면은 보이는 목록 · 열린 메일 · 「예약됨」 첫 항목 가운데 가장 이른 sendAt + 2초에 보이는 목록 · 열린 메일 · 「예약됨」 수를 다시 맞추고, 지난 시각이 아직 보이면 5초마다 몇 번 더 본다. 취소 · 고치기가 MAIL_014 를 받았을 때도 같다(구현하며 정함 — 2026-10-29 리뷰).
DELETE /api/scheduled-messages/{id}(id 는 보낸 사본의 메일 id) — 붙잡은 발송을 취소한다(보내기 취소 · 예약 취소 모두). 엔진에서 취소한 뒤에 그 메일을 임시보관함으로 옮겨 초안으로 되돌린다($draft 와 취소 표시 $ara-canceled 를 붙이고 예약 표시를 뗀다 — 발송 지문 머리글이 남아 있어도 취소 표시가 있으면 사용자 초안이다) → 200 { draftId }(같은 메일 id — 쓰기 화면이 이 id 로 이어 쓴다). 받는 사람 · 제목 · 본문 · 첨부는 그대로다. 이어 쓸 때(구현하며 정함): 서명 그림 부분(Content-ID sig-…)은 첨부에서 빼고 본문의 cid:sig-… 는 서명 그림 주소로 되돌린다(보낼 때 다시 cid: 로 — "서명"), 답장 대상은 같은 스레드에서 In-Reply-To 로 찾아 초안의 inReplyTo 로 준다.
- 이미 보냈거나(엔진이 풀었음 · 보낼 시각이 지나 배달 중) 기다리는 발송이 아닌 메일(제출이 없음)이면 409 MAIL_014 — 아무것도 바꾸지 않는다. 없는 메일은 404 RES_001.
- 다시 취소해도 된다(2026-10-29 리뷰 — 응답이 끊겨 다시 누른 경우): 그 메일의 제출이 모두 canceled 이고 취소 표시($ara-canceled)가 있으면 어느 메일함에 있든 그대로 200 { draftId }(같은 id — 옮기지 않는다: 사용자가 그 초안을 휴지통에 버린 뒤 늦게 온 취소가 되살리지 않게), 표시가 없으면(앞의 옮기기가 실패) 되돌리기를 다시 한다 — 그래도 못 하면 503 MAIL_001.
- 엔진이 취소를 확인하지 않으면(응답의 updated 에 그 제출이 없음 — 거절도 아님) 옮기지 않고 503 MAIL_001 — 옮기면 사용자는 취소된 줄 알지만 엔진은 시간이 되면 보낸다. 다시 부르면 처음부터 다시 본다.
- 서명 그림 부분 빼기 · cid:sig-… 되돌리기는 취소 표시($ara-canceled)가 있는 초안에만 한다(다른 메일 프로그램이 만든 초안의 그림은 건드리지 않는다).
- 취소와 옮기기는 다른 요청이다(같은 요청에 두면 취소가 실패해도 옮겨진다). 취소는 됐는데 옮기지 못하면(엔진 오류) 한 번 더 하고, 그래도 못 하면 503 MAIL_001 — 그 메일은 보내지 않은 채 보낸편지함에 남는다(드묾 — 알려진 한계, warn 로그).
중복 발송 방지와 함께: 취소한 발송의 Idempotency-Key 로 다시 보내면 409 MAIL_005(보내지 않는다) — 클라이언트는 취소 뒤 새 키로 보낸다. 서버는 취소한 발송의 메일을 "보낸 것"으로도, "끊긴 발송이 남긴 초안"으로도 보지 않는다(지우지 않는다). 취소 표시($ara-canceled)가 있으면 제출 기록과 상관없이 취소한 발송이다. 붙잡는 시간은 지문에 넣지 않는다 — 같은 키로 다시 보내면 sendAt 이 달라도 처음 결과(그때의 pendingSend)를 돌려준다. 같은 키의 메일을 찾으면 그 제출을 늘 읽는다(엔진 호출 1회 더 — 제출이 모두 canceled 면 위의 MAIL_005).
보낸 뒤 이어 쓴 저장본(draftId) 지우기는 지금처럼 한다 — 취소하면 붙잡혀 있던 사본이 새 초안이 된다.
붙잡은 메일은 엔진을 다시 띄워도 남는다(엔진의 대기열은 저장소에 있다). 우리 서버는 붙잡은 발송을 따로 기억하지 않는다 — 목록 · 상태는 늘 엔진에 묻는다.
로그: 취소 · 예약은 log(메일 id · 보낼 시각만) — 받는 사람 · 제목은 남기지 않는다.
클라이언트: [보내기]를 누르면 지금처럼 쓰기 화면을 닫고 떠난다. 알림 "메일을 보냈습니다." + [보내기 취소] + 남은 시간 막대 — pendingSend.sendAt 에 닫는다(마우스를 올려도 멈추지 않는다). 일부 거절의 실패 알림에도 [보내기 취소]를 둔다. [보내기 취소] → DELETE → 쓰기 화면을 ?draft=<draftId> 로 다시 연다(새 키) + 알림 "보내기를 취소했습니다. 쓰던 메일로 돌아왔습니다.". MAIL_014 는 인터셉터 알림. 예약은 알림 "‘시각’ 에 보냅니다." + [예약됨 보기]. 세션이 바뀌면 알림을 닫는다 — 메일은 그대로 보내진다.

외부 이미지 보기 (`images=show` · `/api/mail-images`) — 9단계

받은 메일의 외부 이미지는 지금처럼 지운 채 준다(hasBlockedImages). 보이게 할 때는 서버가 그 메일의 이미지 주소를 중계 주소로 바꿔 넣고, 그 주소로 오는 요청에 서버가 바깥 이미지를 대신 받아 준다 — 보낸 쪽 서버에는 직원 PC 의 주소 · 브라우저가 드러나지 않고(우리 서버의 주소만), 화면의 CSP(img-src 'self' data:)도 그대로다. 보낸 쪽은 이미지를 받은 시각으로 메일을 열어 본 것을 알 수 있다 — 그래서 처음 값은 "늘 묻기"다. 화면은 디자인 README "9단계"(디자인 원본 MailReadTools · SettingsSendRead).

GET /api/messages/{id}?images=show — 외부 이미지를 보이는 본문(hasBlockedImages: false — srcset · 배경 그림 · 한도 밖처럼 지운 것이 있어도). imagesShown 은 실제로 바꿔 넣은 그림이 있을 때만 true 다 — 외부 이미지가 없는 메일은 images=show 여도 false(구현하며 정함). 쿼리 없이 물으면 설정(아래 externalImages)을 따른다: ask 는 지금처럼 지우고, trusted 는 보낸 사람이 내 주소록(3절)이나 사내 목록(직원 · 공용 주소 — 3절 "사내 목록")에 있으면 보이고, always 는 늘 보인다. 스팸메일함의 메일은 설정과 상관없이 지운다(images=show 로만 보인다). MessageDetail.imagesShown 이 그 결과다. trusted 에서 주소록 · 사내 목록을 읽지 못하면 보이지 않는 쪽으로 다룬다. 머리글 From 은 꾸밀 수 있다(알려진 한계 — 꾸며도 중계라 직원 PC 의 주소는 드러나지 않는다).
바꾸는 것은 <img> 의 src(http · https · //)뿐이다 — srcset 은 지금처럼 지우고, style · 속성의 배경 그림(url())도 지금처럼 지운다(알려진 한계). 주소 2,048자 이하만, 한 통에 100개까지(그 뒤는 지운다). 같은 주소는 한 통 안에서 같은 중계 주소를 쓴다(브라우저가 한 번만 받는다). 중계 주소는 /api/mail-images/<표> — 표는 직원 · 원래 주소 · 끝나는 시각(1시간)을 서버 비밀로 암호화한(인증 암호 AES-GCM — 고친 표는 풀리지 않는다) 불투명 글이다. 서명만 하면 표를 풀어 원래 주소(추적 번호가 든다)를 읽을 수 있어 접근 로그 · 주소창에 남는다 — 그래서 암호화한다. 키는 서버가 뜰 때 무작위로 만든다(JWT 키와 따로) — 다시 띄우면 옛 표는 404 이고, 메일을 다시 열면 새 표를 받는다. ⚠️ 서버를 여러 대로 늘리면 키를 공유 비밀로 옮긴다.
GET /api/mail-images/{token} — 로그인 필요(쿠키), 표의 직원과 같아야 한다. 서버가 바깥 이미지를 받아 그대로 준다(표준 래퍼 없음):
- 주소: http · https, 기본 포트(80 · 443)만. 이름을 풀어 모든 주소가 공인 주소일 때만, 푼 그 주소로 연결한다(다시 풀지 않는다 — DNS 바꿔치기를 막는다). 막는 곳: 사설(10/8 · 172.16/12 · 192.168/16) · 루프백 · 링크 로컬 · CGNAT(100.64/10) · 멀티캐스트 · 예약 · 문서용 대역, IPv6 의 같은 것(::1 · fc00::/7 · fe80::/10 · ff00::/8 · IPv4 대응 · NAT64) — 우리 도커 망(APP_NETWORK_SUBNET · EDGE_NETWORK_SUBNET)도 사설이라 막힌다(메일 엔진 관리 API · DB 를 부르게 만드는 공격). 점 없는 이름(도커 서비스 이름 등)은 묻지 않고 막는다. 이름은 c-ares(dns.Resolver)로 푼다 — libuv 스레드 풀을 막지 않게(구현하며 정함).
- 다시 가기(redirect)는 3번까지, 매번 위 검사. 전체 10초, 받는 크기 5MB(넘으면 끊는다).
- 형식은 받은 바이트의 앞부분으로 정한다 — PNG · JPEG · GIF · WebP 만(SVG · 그 밖은 거절). 바깥이 보낸 Content-Type 은 믿지 않는다.
- 바깥으로는 쿠키 · Referer 없이, 고정한 User-Agent 로 묻는다.
- 응답: 받은 바이트 + 판정한 Content-Type · Cache-Control: private, max-age=3600 · X-Content-Type-Options: nosniff · Content-Disposition: inline · Content-Security-Policy: default-src 'none'; sandbox.
- 실패는 모두 404 RES_001 — 까닭을 주지 않는다(표가 틀림 · 지남 · 다른 직원 · 막은 주소 · 받지 못함 · 너무 큼 · 그림이 아님). 화면은 그 자리를 비운다. 이 404 는 전역 필터를 거치지 않고 컨트롤러가 직접 쓴다 — 형식 · traceId 는 같고, 로그는 debug 만(바깥 탓의 실패가 잦아 warn 이면 알림이 쌓인다 — 구현하며 정함).
- 동시에 받는 수는 서버 전체 16개 · 한 직원 6개까지(넘으면 기다린다 — 30초 · 200개까지, 넘으면 404). 기다리는 줄은 직원마다이고, 서버 자리가 나면 자기 6개에 막히지 않은 직원 가운데 지금 받는 수가 가장 적은 직원의 맨 앞 요청부터 든다(같으면 먼저 기다린 쪽 — 몇 사람이 서버 자리를 다 차지하지 못하게, 2026-10-29 리뷰 2). 자리는 응답을 다 보낼(또는 브라우저가 끊을) 때까지 쥔다 — 메모리에 쥐는 그림은 많아야 16 × 5MB(구현하며 정함 — 2026-10-29 리뷰). 요청 수 한도는 이 경로만 넉넉하게 — IP 마다 1분 600회(뉴스레터 한 통에 이미지가 수십 개, 사무실 NAT).
- 로그: 주소는 남기지 않는다(추적 번호 · 개인 정보가 들어 있다) — 실패 까닭과 바깥 호스트 이름만 debug. 요청 주소를 남기는 로그의 /api/mail-images/<표> 는 글자 수만 남긴다(maskUrlForLog).
화면: 본문 틀의 내부 CSP 를 보일 때만 img-src data: <화면 주소>/api/mail-images/ 로 넓히고(중계 경로만 — 'self' 면 정화를 빠져나간 CSS url() 이 같은 출처의 다른 API 를 부를 수 있다, 2026-10-29 리뷰), 클라이언트 정화(DOMPurify)도 /api/mail-images/ 로 시작하는 주소만 남긴다(그 밖의 바깥 주소는 지금처럼 지운다). 답장 · 전달 인용에는 이미지가 실리지 않는다(보내는 정화가 서명 그림 밖의 img 를 지운다 — 중계 주소가 바깥으로 나가지 않는다).
운영 확인: 백엔드 컨테이너가 바깥 80 · 443 으로 나갈 수 있어야 한다(호스트 방화벽 · 프록시) — 막혀 있으면 이미지 자리가 비어 보인다. 막기는 사설 대역에 기대므로 도커 망(APP_NETWORK_SUBNET · EDGE_NETWORK_SUBNET)은 사설 대역으로 둔다. 서버 자신의 공인 주소로 풀리는 이름은 공인 주소라 막지 않는다 — 같은 외부 프록시 뒤에 "내부 주소면 허용"하는 다른 사이트를 두지 않는다(2026-10-29 리뷰, 운영 절차는 docker 스킬).

인쇄 — 9단계

API 는 새로 없다. 인쇄 화면(새 탭 — 메일 한 통, 디자인 원본 MailPrint)은 GET /api/messages/{id} 로 그린다 — 읽기 화면에서 외부 이미지를 보이고 있었으면 images=show.

보낸 사람 차단 (`/api/mail-blocks`) — 9단계

interface BlockedSender {
  address: string      // 소문자로 맞춘 주소("kim@spam.example") 또는 도메인("@spam.example" — 그 도메인에서 오는 메일 모두. 하위 도메인은 따로)
  blockedAt: string    // 차단한 시각(UTC)
}
interface MailBlockList {
  senders: BlockedSender[]   // 최근에 차단한 것부터, 500개까지
  isActive: boolean          // 엔진에서 우리 규칙(필터 · 부재중과 같은 Sieve 스크립트)이 켜져 있는지 — 필터의 isActive 와 같다
}

효과: 차단한 보낸 사람(머리글 From 의 주소 · 도메인 — 대소문자 무시)의 메일은 스팸메일함으로 간다. 필터 · 부재중보다 먼저 돌고 멈추므로 필터는 돌지 않고 부재중 응답도 나가지 않는다. 이미 받은 메일은 옮기지 않는다 — 읽기 화면의 차단 창은 그 메일만 함께 스팸메일함으로 옮긴다(PATCH /api/messages/{id} 의 isJunk).
검사: 주소는 발송의 주소와 같은 규칙에 @ 앞은 dot-atom · 64자까지(따옴표 앞부분은 받지 않는다 — 클라이언트의 isStrictEmail 과 같은 폭, 2026-10-29 리뷰), 도메인은 @ + 호스트 이름(점이 하나 이상 · 253자 · IP 주소 아님 · ASCII 만 — 국제화 도메인은 xn-- 꼴로, ${ 는 받지 않는다). 이미 차단한 주소를 다시 POST 하면 200 — 엔진에서 규칙이 꺼져 있었으면 같은 원본을 다시 써서 켠다. 그래서 POST · DELETE 가 성공한 뒤에는 늘 켜져 있다(isActive: true). 내 주소와 사내 도메인(MAIL_DOMAIN 과 그 하위)은 막을 수 없다. 여러 사람이 쓰는 메일 서비스(gmail.com · naver.com · daum.net · hanmail.net · kakao.com · nate.com · outlook.com · hotmail.com · live.com · yahoo.com · icloud.com 등 — 목록은 서버 상수)는 도메인으로 막을 수 없다(주소로는 된다). 클라이언트도 같은 목록을 먼저 본다(짝 — 한쪽을 고치면 둘 다). 500개를 넘으면 400 VAL_001.
저장 자리: 필터 · 부재중과 같은 Sieve 스크립트(arasystem — 6단계)의 맨 앞. 머리 주석의 원본(JSON)에 blocked(주소 · 차단한 시각)를 더하고, 원본 판은 차단한 주소가 있을 때만 2 로 쓴다(없으면 지금처럼 1). 판 2 를 아는 서버는 판 1 을 "차단 없음"으로 읽는다. 판 2 를 모르는 옛 서버로 되돌리면 차단한 주소가 있는 직원만 필터 · 부재중 · 차단 저장이 503 MAIL_001 로 막힌다 (옛 서버가 새 판을 지우지 않게 — 6단계의 규칙). 되돌리기 계획: 판 2 를 읽기만 하는 서버를 먼저 배포할 수 있게 둔다. 만든 Sieve(스팸 표시 감싸기 밖 · 필터 · 부재중 앞): if anyof (address :all :is "from" [주소들], address :domain :is "from" [도메인들]) { fileinto :mailboxid "<스팸메일함 id>" "<스팸메일함 이름>"; stop; }. 비교는 엔진 기본(i;ascii-casemap — ASCII 대소문자 무시)이다 — 엔진의 Sieve 확장 목록에 comparator-i;unicode-casemap 이 없어 :comparator 를 뺐다(구현하며 정함 — 주소 앞부분의 ASCII 밖 글자는 대소문자를 가린다, 한계). fileinto 의 대체 이름은 실제 스팸메일함 이름이다(비었거나 ${ 가 들어 있으면 "Junk"). 스팸메일함이 없으면 503 MAIL_001. 실제 배달로 확인했다(2026-10-29, 38가지 — 대소문자를 섞은 주소 · 도메인은 스팸메일함으로, 하위 도메인 · 이름만 같은 다른 도메인 · 차단하지 않은 주소는 손대지 않음, 차단이 있어도 사내 직원의 메일은 받은편지함. SieveScript/validate 는 모르는 test 이름을 걸러 주지 않아 배달로 본다).
스크립트 크기 한도(90,000바이트)를 필터와 함께 쓴다 — 넘으면 400 MAIL_013(사전 문구가 필터 · 차단 목록을 함께 말한다).
쓰기는 필터처럼 읽은 상태 그대로일 때만(ifInState) · 어긋나면 다시 읽어 세 번까지. 차단은 필터의 version 을 묻지 않는다(주소 하나를 더하고 빼는 일이라 그사이 바뀐 필터를 덮지 않는다).
로그: 주소는 가린다(maskEmail — 도메인 차단은 도메인만).
클라이언트: 읽기 화면 ⋯ 「보낸 사람 차단」(사내 직원 · 내 주소면 없고, 이미 차단했으면 「보낸 사람 차단 풀기」, 500개면 꺼짐 + 까닭) → 확인 창(이 주소만 · 이 도메인 전체, 「이 메일도 스팸메일함으로 옮기기」) → POST(+ 옮기기) → 알림 + [되돌리기](차단을 풀고 메일을 원래 메일함으로 — 구현하며 정함). 설정 › 메일 › 차단한 주소에서 더하고 푼다. 스팸메일함에서 차단한 보낸 사람의 메일을 열면 안내 줄 + [차단 풀기]. 차단 목록은 메일 화면에 들어올 때 받아 둔다.

보내기 · 읽기 설정 (`/api/mail-settings`) — 9단계

직원마다의 설정을 서버 DB 에 둔다(표 mail_settings — 직원 주소마다 한 줄, 없으면 처음 값). 어느 PC 에서나 같다.

interface MailSettings {
  undoSendSeconds: 0 | 5 | 10 | 20 | 30          // 보내기 취소 — 0 이면 바로 보낸다. 처음 10
  externalImages: 'ask' | 'trusted' | 'always'   // 외부 이미지 — 늘 묻기 · 주소록과 사내 직원은 늘 보기 · 늘 보기. 처음 'ask'
}

서버는 발송 때 undoSendSeconds, 메일을 읽을 때 externalImages 를 본다(직원마다 잠깐 기억해도 된다 — 그 서버에서 바꾸면 바로 맞춘다). 서버마다 60초 기억하고, 읽지 못하면(DB 장애) 처음 값(10초 · ask)으로 보고 warn 을 남긴다(구현하며 정함).
화면(설정 › 메일 › 보내기 · 읽기)은 고르는 대로 PATCH 하고 "저장했습니다"를 보인다(저장 단추 없음). 칸마다 저장은 한 번에 하나다 — 끝났을 때 마지막으로 고른 값이 서버의 답과 다르면 그 값을 다시 보낸다(늦게 온 앞 응답 때문에 화면과 서버가 갈리지 않게 — 2026-10-29 리뷰). "저장했습니다"는 기다리던 저장이 모두 끝나고 마지막이 성공했을 때 보인다. 끝내 실패하면 서버가 마지막으로 확인해 준 값으로 되돌리고 인터셉터가 알린다.

이 단계에서 하지 않는 것

탭을 모두 닫아도 오는 알림(웹 푸시 — 엔진은 webpush-vapid 를 지원한다), 알림 소리(운영체제 설정을 따른다), 휴대폰 푸시, 본문 안 이미지(인라인 cid — 붙여 넣은 이미지는 첨부로, 서명 그림만 예외), 메일 안의 배경 그림 보이기 · 보낸 사람마다 고르는 "이미지 늘 보기" 목록(9단계는 설정 세 가지로), 여러 개의 서명, 자체 검색 색인(붙여 쓴 말 · 앞부분 · 제목 말머리로 찾기), 조건 검색(보낸 사람 · 기간 · 첨부 있음), 검색어 강조, 끌어다 놓아 옮기기, 메일함 옮기기(다른 상위로) · 하위 메일함까지 한꺼번에 지우기, 앱 비밀번호 · 2단계 인증(엔진은 지원한다), 부재중 응답의 서식 본문 · 사내/외부 구분, 예약한 메일의 「지금 보내기」 · 7일 넘는 예약(엔진 한도) · 차단할 때 이미 받은 그 보낸 사람의 메일 모두 옮기기(9단계는 그 메일만).

3. 주소록 — 8단계 (모두 로그인 필요 — 없으면 401 `AUTH_001`)

직원마다의 내 주소록(연락처 · 그룹)과 모두가 함께 보는 사내 목록(직원 · 공용 주소)이다. 화면은 디자인 README "8단계"(디자인 원본 Contacts · ContactsEdit · ContactsMail).

내 주소록은 메일 엔진의 주소록에 둔다 — 직원마다 엔진의 기본 주소록 하나(JMAP Contacts · JSContact 카드). 서버는 게이트웨이 대리 접근으로 그 직원의 주소록만 읽고 쓴다. 같은 주소록을 나중에 휴대폰 · 메일 프로그램(CardDAV)에서도 쓸 수 있다 — 그래서 서버는 우리가 다루지 않는 칸(주소 · 생일 · 사진 등)을 고칠 때 그대로 둔다.
사내 목록은 엔진의 계정 목록(JMAP Principal)에서 이름 · 주소만 읽는다. 직원 역할은 계정 목록을 볼 수 없게 막아 두었으므로(1단계 setup) setup 이 만든 전용 계정으로만 읽는다(아래 "사내 목록").

타입

type ContactEmailLabel = 'work' | 'personal' | 'other'          // 회사 · 개인 · 기타
type ContactPhoneLabel = 'mobile' | 'work' | 'home' | 'other'   // 휴대전화 · 회사 · 집 · 기타

interface ContactEmail { address: string; label: ContactEmailLabel }
interface ContactPhone { number: string; label: ContactPhoneLabel }

interface Contact {
  id: string
  name: string | null          // 표시 이름(엔진 카드의 name.full — 없으면 이름 조각을 이어 붙인 것)
  emails: ContactEmail[]       // 앞의 것이 대표 주소 — 받는 사람 추천의 첫 줄 · 그룹으로 보낼 때 쓴다
  phones: ContactPhone[]
  company: string | null
  department: string | null
  title: string | null         // 직책
  note: string | null          // 메모 (줄바꿈 있음)
  groupIds: string[]           // 속한 그룹 — 이 주소록의 그룹만
}

interface ContactInput {       // POST 본문(고치기는 아래 ContactPatch) — 서버는 앞뒤 공백을 빼고 저장한다(빈 글은 null)
  name: string | null          // 100자까지
  emails: ContactEmail[]       // 20개까지(화면은 5개까지 더한다 — 다른 프로그램이 넣은 것은 그대로 보이고 저장된다), 주소 254자 · 메일 주소 형식 · 같은 연락처 안에서 겹치지 않게(대소문자 무시)
  phones: ContactPhone[]       // 20개까지, 번호 40자 — 숫자가 하나 이상이고 숫자 · 띄어쓰기 · + - ( ) . # * 만
  company: string | null       // 100자
  department: string | null    // 100자
  title: string | null         // 100자
  note: string | null          // 1,000자 — 줄바꿈(\n)은 되고 그 밖의 제어 문자는 안 된다
  groupIds: string[]           // 100개까지, 겹치지 않게
}
// 이름이나 이메일 가운데 하나는 있어야 한다(둘 다 없으면 400 VAL_001). 글자 수는 JS 문자열 길이(UTF-16) — 웹의 .length 와 같다.

type ContactPatch = Partial<ContactInput>   // PATCH 본문 — 바꾼 칸만(하나 이상 — 비면 400 VAL_001). 보낸 칸만 위 규칙으로 보고, "이름이나 이메일"은 합친 결과로 본다.
// emails · phones · groupIds 는 보내면 그 칸이 통째로 바뀐다. 보내지 않은 칸은 검사하지도 바꾸지도 않는다 — 아래 "고치기".

interface ContactDeleted {     // 연락처 지우기의 응답
  contact: Contact             // 지운 연락처
  restoreToken: string | null  // [되돌리기] 표 — 아래 "되돌리기" (서버가 기억하지 못했으면 null — 화면은 [되돌리기] 없이 알린다)
}

interface ContactGroup {
  id: string
  name: string                 // 1~50자, 이 주소록 안에서 겹치지 않는다(앞뒤 공백을 빼고 ASCII 대소문자를 무시하고 견준다)
  memberCount: number          // 이 주소록에 있는 연락처 가운데 구성원 수
}

interface ContactGroupDeleted {   // 그룹 지우기의 응답
  id: string
  name: string
  memberIds: string[]
  restoreToken: string | null     // [되돌리기] 표 — 아래 "되돌리기"
}

type ContactRestored =            // 되돌리기의 응답 — 다시 만든 것(id 는 새로 받는다)
  | { kind: 'contact'; contact: Contact }
  | { kind: 'group'; group: ContactGroup }

interface ContactGroupMembersAdded {
  group: ContactGroup
  addedCount: number           // 이번에 그룹에 들어간 수 (이미 구성원이던 것은 세지 않는다)
  createdCount: number         // 사내 목록에서 골라 내 주소록에 새로 만든 연락처 수
}

interface DirectoryEntry {
  id: string                   // 엔진의 계정 id
  name: string                 // 엔진의 표시 이름 — 없으면 주소의 @ 앞
  email: string
  kind: 'person' | 'shared'    // 직원(개인 계정) · 공용 주소(그룹 계정)
}

엔드포인트

메서드 · 경로	요청	성공	주요 실패
`GET /api/contacts`	`q`(선택, 1~254자) · `groupId`(선택 — 그 그룹의 구성원만) · `excludeGroupId`(선택 — 그 그룹의 구성원을 빼고. `groupId` 와 함께 쓰지 않는다) · `cursor` · `limit`(기본 20, 최대 100)	200 `{ items: Contact[], pageInfo }` — 이름 차례(아래), `total` 포함	400 `VAL_001`, 404 `RES_001`(없는 그룹), 503 `MAIL_001`
`GET /api/contacts/{id}`	—	200 `Contact`	404 `RES_001`, 503 `MAIL_001`
`POST /api/contacts`	`ContactInput`	201 `Contact`	400 `VAL_001`, 404 `RES_001`(없는 groupId), 409 `CONTACT_002`(연락처 3,000개 · 그룹 구성원 500명 · 크기), 503 `MAIL_001`
`PATCH /api/contacts/{id}`	`ContactPatch` — 바꾼 칸만(보내지 않은 칸 · 엔진 카드의 다른 칸은 그대로 — 아래 "고치기")	200 `Contact`	400 `VAL_001`, 404 `RES_001`, 409 `CONTACT_002`(그룹 구성원 500명 · 크기), 503 `MAIL_001`
`DELETE /api/contacts/{id}`	—	200 `ContactDeleted` — 지운 연락처(그룹에서도 뺀다)와 되돌리기 표	404 `RES_001`, 503 `MAIL_001`
`GET /api/contact-groups`	`cursor` · `limit`(기본 20, 최대 100)	200 `{ items: ContactGroup[], pageInfo }` — 이름 차례	503 `MAIL_001`
`POST /api/contact-groups`	`{ name }`	201 `ContactGroup`	400 `VAL_001`, 409 `CONTACT_001`(같은 이름) · `CONTACT_002`(그룹 100개), 503 `MAIL_001`
`PATCH /api/contact-groups/{id}`	`{ name }`	200 `ContactGroup`	400 `VAL_001`, 404 `RES_001`, 409 `CONTACT_001`, 503 `MAIL_001`
`DELETE /api/contact-groups/{id}`	—	200 `ContactGroupDeleted` — 연락처는 그대로	404 `RES_001`, 503 `MAIL_001`
`POST /api/contact-restorations`	`{ token }` — 지우기 응답의 `restoreToken`	201 `ContactRestored` — 지운 그대로 다시 만든 연락처 · 그룹(아래 "되돌리기")	400 `VAL_001`, 404 `RES_001`(표가 없음 · 지남 · 이미 씀), 409 `CONTACT_001` · `CONTACT_002`, 503 `MAIL_001`
`POST /api/contact-groups/{id}/members`	`{ contactIds?, directoryIds? }` — 합쳐 1~100개	200 `ContactGroupMembersAdded`	400 `VAL_001`, 404 `RES_001`(없는 그룹 · 연락처 · 사내 목록 id), 409 `CONTACT_002`, 503 `MAIL_001`
`GET /api/directory-entries`	`q`(선택, 1~254자) · `kind`(선택 — `person` · `shared`) · `excludeGroupId`(선택 — 그 그룹 구성원의 주소를 뺀다. 구성원 넣기 창) · `cursor` · `limit`(기본 20, 최대 100)	200 `{ items: DirectoryEntry[], pageInfo }` — 이름 차례, `total` 포함	400 `VAL_001`, 404 `RES_001`(없는 그룹), 503 `MAIL_001`(사내 목록을 읽지 못함 — 아래 "사내 목록")
`GET /api/directory-entries/{id}`	—	200 `DirectoryEntry`	404 `RES_001`(없거나 빼는 계정), 503 `MAIL_001`

에러 코드(8단계에 더함): CONTACT_001 409 — 같은 이름의 그룹이 있다(만들기 · 이름 바꾸기 — 화면은 칸 아래에, 알림 없이). CONTACT_002 409 — 주소록 한도(연락처 3,000개 · 그룹 100개 · 그룹 하나에 구성원 500명 · 아래 "크기")를 넘는다 — 아무것도 바꾸지 않는다 (사전 문구에는 앞의 세 한도가 나온다 — 크기는 보통 쓰임으로는 닿지 않는다).
cursor 는 불투명 문자열이고 받은 그 q · groupId · excludeGroupId · kind 로만 쓴다(다르면 400 VAL_001). 차례 사이에 연락처가 바뀌면 다음 쪽에서 한두 개가 겹치거나 빠질 수 있다.
차례: 이름(한국어 사전 차례 — Intl.Collator('ko')), 이름이 없으면 대표 주소로 견준다. 같으면 대표 주소 → id.
찾기(q): 초성만 친 글(ㄱ~ㅎ, 겹자음 포함)이면 이름의 초성과 견준다(ㅂㅈㅎ → 박지훈). 그 밖에는 이름 · 주소 · 회사 · 부서 · 직책 · 전화번호에 그 글이 들어 있으면 맞다 (ASCII 대소문자 무시). 전화번호는 숫자만 견준다(01031925540 · 3192 가 010-3192-5540 에 맞는다). 사내 목록은 이름 · 주소로 같은 규칙. 엔진의 주소록 검색은 낱말 단위이고 이름 정렬을 하지 못해서(2026-10-29 확인 — '김아라'로 못 찾고 name 정렬은 unsupportedSort) 서버가 주소록 전체를 읽어 찾고 정렬한다.
엔진에 두는 모양(서버 책임): 연락처는 JSContact kind: individual, 그룹은 kind: group(구성원은 members — 카드의 uid 로 잇는다). 만들 때 서버가 uid(urn:uuid:…)를 넣는다 — 넣지 않으면 엔진이 uid 를 주지 않아 그룹에 이을 수 없다(2026-10-29 확인). 엔진은 만든 뒤 uid 를 바꾸지 못하게 한다("You cannot change the UID of a contact.") — 그래서 다른 프로그램이 uid 없이 만든 카드는 그룹에 넣을 수 없다: PATCH 의 groupIds 에 새 그룹을 넣으면 400 VAL_001, 구성원 넣기에서는 건너뛰고 세지 않는다(CardDAV 프로그램은 늘 UID 를 넣는다 — 드물다). 그룹 구성원을 바꿀 때는 members 를 통째로 쓴다(엔진이 구성원 없는 그룹의 members/<uid> 패치를 받지 않는다). 칸: name.full · emails(종류는 contexts — work · private, 대표 주소는 pref: 1) · phones(휴대전화는 features.mobile, 회사 · 집은 contexts work · private) · organizations(이름 · units 첫째가 부서) · titles(kind: title) · notes. 고치기는 이 칸만 패치한다 — 다른 칸(주소 · 생일 · 사진 · 다른 프로그램의 칸)은 그대로 둔다. 칸 안에서도 우리가 정하지 않는 것은 그대로 둔다(아래 "고치기"). 엔진에 주소록이 여럿이면 기본 주소록(isDefault)만 쓴다. 그룹 구성원 수는 이 주소록에 있는 연락처만 센다(지워진 카드를 가리키는 uid 는 세지 않는다).
캐시: 주소록 전체 읽기는 300장에 0.4초 남짓이라(개발 엔진) 서버는 직원마다 주소록을 엔진의 상태(state)와 함께 기억하고, 요청마다 상태만 물어(ContactCard/get 의 빈 ids — 3ms) 바뀌지 않았으면 다시 읽지 않는다 (서버 메모리 — 200명 · 모두 합쳐 2,400만, 한 사람 800만까지(아래 "크기"와 같은 잣대) — "크기" 안의 주소록은 늘 통째로 기억할 수 있다. 그보다 큰 주소록(다른 프로그램이 크게 만든 것)은 기억하지 않고 요청마다 다시 읽는다. 30분 쓰지 않으면 잊는다. 다른 프로그램에서 바꾼 것도 상태가 바뀌어 곧 보인다 — 그때는 주소록 전체를 다시 읽는다, 3,000장에 3초 남짓). 엔진에서 한 번에 읽는 상한은 카드 5,000장 · 계정 10,000개다(넘으면 앞쪽만 — warn 로그).
쓰기: 같은 직원의 바꾸기는 차례로 한다. 엔진에는 읽은 상태 그대로일 때만 쓰고(ifInState), 그사이 바뀌면 다시 읽어 다시 정한다 — 세 번 어긋나면 503 MAIL_001. 한도 · 같은 이름 검사도 같은 판으로 본다. 엔진에는 바뀐 칸만 보낸다(회사 · 부서는 한 조직이라 하나만 바뀌어도 함께). 엔진이 serverUnavailable 로 거절하면(메서드 오류든 항목 오류든) 판을 다시 읽어 다시 한다(위 세 번 안에서 — 일부만 들어갔을 수 있어 만들기 · 되돌리기는 같은 uid 로 이미 들어간 카드를 찾는다). ⚠️ 엔진은 한 요청의 destroy 에 같은 id 가 두 번 있으면 요청 전체를 serverUnavailable(store.assert-value-failed)로 거절한다(2026-10-29 확인 — 몇 번을 다시 해도 같다) — 서버는 한 요청에 같은 카드를 두 번 넣지 않는다. 판은 읽기 전에 물은 것으로 잡는다 — 읽는 사이 다른 곳에서 만든 카드를 빠뜨린 채 "최신"으로 기억하지 않게.
크기: 서버가 재는 주소록 크기(연락처 · 그룹에서 우리가 다루는 칸의 글자 수 + 항목마다 조금 — 위 캐시가 쓰는 잣대)를 800만 넘게 하는 쓰기 (만들기 · 고치기 · 구성원 넣기 · 되돌리기)는 409 CONTACT_002 다 — 줄이는 쓰기와 지우기는 늘 된다. 연락처 3,000개에 그룹 100개를 구성원 500명씩 다 채워도 연락처마다 1,000자 넘게 남아 보통 쓰임으로는 닿지 않는다. 캐시가 주소록 하나를 통째로 기억할 수 있게 둔 한도다 (2026-10-29 리뷰: 칸마다 최대인 연락처 3,000장은 2,400만이라 기억하지 못하고, 요청마다 엔진에서 다시 읽어 1초씩 멈췄다).
고치기(PATCH): 화면은 창을 열 때 그 연락처를 새로 받고(GET /api/contacts/{id}), 연 때와 달라진 칸만 보낸다 — 창을 연 사이 다른 탭 · 휴대폰에서 바꾼 다른 칸을 덮지 않는다. 같은 칸을 양쪽에서 바꿨으면 나중에 저장한 쪽이 이긴다(판을 묻지 않는다). 보내지 않은 칸은 검사하지 않는다 — 다른 프로그램이 우리 규칙 밖의 값(21번째 주소 · "내선"이 든 번호 · 1,000자 넘는 메모)을 넣었어도 다른 칸은 고칠 수 있다(그 칸을 고칠 때는 그 값도 규칙에 맞춰야 한다). 칸 안의 남의 정보도 지킨다 — 서버는 보낸 주소를 지금 카드의 같은 주소(대소문자 무시)와, 번호는 보인 글이 같은 것 먼저 · 그다음 숫자가 같은 것과 짝지어 그 항목의 다른 속성(label · 다른 contexts · fax 같은 features · pref)을 남기고, 종류를 바꾼 것만 우리 값(contexts work · private, features.mobile)으로 고친다. 대표 주소(pref: 1)는 첫 주소에만 둔다 — 다른 항목의 pref 는 남기되 1 이거나 읽는 차례(pref → 넣은 차례)를 보낸 차례와 다르게 만들면 뺀다. 직책은 role 이 아닌 첫 항목만 고치고 지우면 그 항목만 뺀다(다른 직책 항목이 있으면 그것이 보인다). 회사 · 부서는 첫 조직의 이름과 첫 units 만 고친다 (다른 조직 · 다른 부서는 그대로 — 둘 다 비워 그 조직에 남는 것이 없으면 조직째 뺀다). 메모는 하나로 쓰고(여러 개였으면 이어 보인 글을 고친 것이라) 첫 항목의 다른 속성은 남긴다. 이름을 고치면 { full } 로 쓴다 — 이름 조각(name.components)과 거기 딸린 칸은 지운다(옛 조각이 다른 프로그램에 옛 이름으로 보이지 않게). 엔진은 받은 값을 조금 손봐 저장한다(객체 안 키 차례 · title 을 role 앞에 · role 에 organizationId · 주소에 isOrdered — 2026-10-29 확인) — 응답과 캐시는 서버가 보낸 카드를 다시 읽은 모양이다.
응답: GET 응답에는 Cache-Control: private, no-store 를 붙인다. 그룹 목록의 pageInfo.total 은 그룹 수다.
지우기: 연락처를 지우면 그 연락처를 가리키는 그룹 구성원도 함께 뺀다. 영구 삭제다(엔진 주소록에는 휴지통이 없다) — 화면은 확인 없이 지우고 10초 [되돌리기]로 다시 만든다.
되돌리기(POST /api/contact-restorations): 서버는 지우기 직전에 엔진 카드 전체(다른 프로그램의 칸 · uid 포함)와 그때 속한 그룹(연락처) · 구성원(그룹)을 읽어 직원마다 5분 기억하고(서버 메모리 — 직원마다 최근 20개 · 모두 합쳐 32MB, 카드 하나가 256KB 를 넘으면 기억하지 않는다 — 표 null) 지우기 응답에 표를 준다. 되돌리기는 그 원본을 그대로 다시 만든다 — 같은 uid(그사이 이 주소록의 다른 카드가 그 uid 를 쓰면 새 uid — 엔진은 같은 주소록 안의 같은 uid 를 거절한다, 다른 주소록이면 받는다), 우리 규칙 밖의 값도 그대로. uid 가 없던 원본은 새 uid 로 만든다(되돌린 뒤에는 그룹에 넣을 수 있다). 엔진이 다시 만들기를 받지 않으면 503 MAIL_001 이다(드묾 — 엔진은 공급자 전용 칸(example.com:custom 꼴)이 든 카드를 만들 때 거절한다). 연락처는 그때 속했고 지금도 있는 그룹에 다시 넣고(구성원 500명이 찬 그룹은 건너뛴다), 그룹은 그때의 구성원 가운데 지금도 있는 연락처로 다시 만든다(같은 이름의 그룹이 그사이 생겼으면 409 CONTACT_001, 그룹 100개 · 연락처 3,000개 · 크기는 409 CONTACT_002). id 는 새로 받는다. 표는 한 번만 쓴다(성공하면 지운다 — 실패하면 5분 안에 다시 쓸 수 있다). 표가 없거나 지났거나 이미 썼거나 다른 직원의 것이면 404 RES_001(서버를 다시 띄우면 표는 사라진다). ⚠️ 서버를 여러 대로 늘리면 표도 공유 저장소로 옮겨야 한다(다른 인스턴스로 간 되돌리기는 404).
로그: 연락처의 이름 · 주소 · 전화번호 · 메모는 남기지 않는다(개수 · id 만). q 는 요청 URL 로그에서 길이만 남는다(maskUrlForLog). 되돌리기 표도 남기지 않는다.
알려진 한계 · CardDAV 를 열기 전에 할 일: 지금은 공개 443 이 잠겨(1단계 setup) 엔진 주소록에 쓰는 길이 우리 API 뿐이다. 휴대폰 · 메일 프로그램(CardDAV)에 열기 전에 엔진 응답에 바이트 상한을 두고(지금은 카드 수 5,000장만 막는다 — 사진이 든 카드 500장 한 쪽이 수백 MB 일 수 있다) 위 "크기"를 넘는 주소록의 읽기 비용을 다시 본다.

사내 목록 (`/api/directory-entries`)

엔진의 계정 목록 — 개인 계정은 직원(person), 그룹 계정은 공용 주소(shared). 이름은 엔진의 표시 이름이다(계정의 설명 — 관리 화면에서 넣는 이름).
빼는 계정: 엔진 관리자 · 게이트웨이 · 사내 목록 계정 · 막은 계정(MAIL_BLOCKED_ACCOUNTS) · setup 이 만든 계정(설명에 [setup.mjs]) — 웹메일 로그인의 정적 목록과 같다. 로그인 때 엔진에 묻는 관리 권한 확인은 여기에 없다(엔진의 계정 목록에는 역할이 없다) — 엔진 관리자 아이디 밖의 다른 관리자 계정은 MAIL_BLOCKED_ACCOUNTS 에 넣어야 빠진다. 개인 · 그룹이 아닌 계정(자원 등)도 뺀다. 주소가 MAIL_DOMAIN 이 아닌 계정과 주소가 없는 계정도 뺀다.
읽는 길: setup 이 만든 사내 목록 계정(<MAIL_DIRECTORY_LOCAL_PART>@<MAIL_DOMAIN> — 기본 mail-directory). 그 계정의 역할에는 로그인과 계정 목록 읽기 (authenticate · jmapPrincipalGet · jmapPrincipalQuery)만 있고 비밀번호가 없다 — 서버만 게이트웨이 대리 접근으로 쓴다. 엔진이 주는 칸은 id · 종류 · 로그인 이름 · 표시 이름 · 주소뿐이다 (비밀번호 같은 칸은 없다 — 2026-10-29 확인). 이 권한은 엔진 관리자가 내주지도 빼지도 못해 setup 이 복구 관리자로 실행될 때 만든다(개발은 늘, 운영은 첫 배포의 --recovery — mail/README.md "사내 목록 계정"). 이 계정은 메일을 받지 않는다 — 그 주소(+태그 꼴 포함)로 오는 메일은 받는 쪽 RCPT 단계에서 없는 주소처럼 550 이다(setup 이 관리자 · 게이트웨이와 함께 맞춘다 — 받아 놓고 보낸 사람에게 반송하지 않게, mail/README.md "보안"). 그 뒤의 막으로 역할에 메일 받기 권한이 없고 저장 한도도 1MiB 다.
서버는 목록을 10분 기억한다(모든 직원이 함께 — 서버 메모리). 사내 목록 계정이 없거나 읽지 못하면 503 MAIL_001 이고, 받는 사람 추천의 "사내"는 전처럼 로그인한 직원 기록으로 대신한다.
한 항목(GET /api/directory-entries/{id})은 그 기억한 목록에서 찾는다 — 화면이 주소로 연 사내 항목. excludeGroupId 는 그 직원 주소록의 그 그룹 구성원이 가진 주소(대소문자 무시)를 뺀다.

메일과 함께 (2절과 이어지는 것)

받는 사람 추천(2절 /api/recipient-suggestions)에 내 주소록을 더한다 — source: 'contact'(주소마다 한 줄, 대표 주소가 먼저. 나와 시스템 계정(엔진 관리자 · 게이트웨이 · 사내 목록 계정 · 막은 계정)과 주소 모양(아이디@도메인)이 아닌 것만 빼고, noreply 류도 직원이 넣은 것이라 그대로 둔다). 순서는 주소록 → 사내 → 최근 주고받은 주소이고, 여러 묶음에 있는 주소는 앞 묶음에 한 번만 나온다. "사내"는 사내 목록(위)의 직원 · 공용 주소다 — 사내 목록을 읽지 못하면 전처럼 로그인한 직원 기록(최근 90일). 주소록 묶음은 추천 캐시(10분)에 넣지 않고 요청마다 그 직원의 주소록(위의 상태로 확인한 캐시)에서 붙인다 — 연락처를 바꾸면 다음 추천에 바로 보인다. 주소록을 읽지 못하면 그 묶음만 빼고 답한다(warn 로그).
그룹은 추천 응답에 넣지 않는다 — 클라이언트가 쓰기 화면을 열 때 GET /api/contact-groups 를 한 번 받아 그룹 이름으로 찾고 "주소록" 다음 묶음으로 보인다. 그룹을 고르면 GET /api/contacts?groupId=…&limit=100 으로 구성원을 받아(100명 넘으면 다음 쪽까지) 대표 주소를 받는 사람에 넣는다 — 이메일이 없는 구성원 · 이미 넣은 주소는 뺀다.
쓰기 화면을 받는 사람을 채워 연다(연락처 · 그룹 · 사내의 [메일 쓰기]): 주소는 화면 주소(URL)에 싣지 않고 라우터 상태로 넘긴다 — 브라우저 기록 · 서버 로그에 남지 않게. 상태에는 연 직원의 주소를 함께 싣고, 지금 로그인한 직원과 다르면 쓰지 않는다(같은 탭에서 다른 직원이 로그인한 뒤 뒤로 가기로 돌아온 경우 — 2026-10-29 리뷰).
읽기 화면 ⋯: 보낸 사람 주소가 내 주소록에 없으면 「보낸 사람을 주소록에 추가」(이름 · 주소를 채운 연락처 추가 창), 있으면 「주소록에서 보기」. 판단은 메뉴를 열 때 GET /api/contacts?q=<보낸 사람 주소> 로 알림 없이 하고, 주소가 같은(대소문자 무시) 연락처가 있는지 본다.

173 KiB Raw Blame History Unescape Escape

인증·메일 API 계약 (1단계)

1. 인증 (쿠키 기반 — 토큰은 응답 본문에 없다)

POST /api/auth/login

GET /api/auth/me

POST /api/auth/refresh

POST /api/auth/logout

PUT /api/auth/password — 4단계

클라이언트 처리 규칙

2. 메일 (모두 로그인 필요 — 없으면 401 AUTH_001)

타입

엔드포인트

발송 본문 (POST /api/messages)

첨부 업로드 한도

임시 저장 (/api/drafts)

서명 (/api/mail-signature)

받는 사람 추천 (/api/recipient-suggestions)

새 메일 확인 (/api/mail-state) — 3단계

검색 (GET /api/messages 의 q) — 3단계

여러 통 한꺼번에 (PATCH /api/messages · POST /api/message-deletions) — 3단계

메일함 관리 (/api/mailboxes) — 4단계

부재중 자동 응답 (/api/mail-vacation) — 4단계

스팸 · 원문 — 4단계

실시간 알림 (GET /api/mail-events) — 5단계

메일 필터 (/api/mail-filters) — 6단계

이미 받은 메일에 적용 (/api/mail-filter-runs) — 7단계

보내기 취소 · 예약 발송 (POST /api/messages 의 기다리기 · /api/scheduled-messages) — 9단계

외부 이미지 보기 (images=show · /api/mail-images) — 9단계

인쇄 — 9단계

보낸 사람 차단 (/api/mail-blocks) — 9단계

보내기 · 읽기 설정 (/api/mail-settings) — 9단계

이 단계에서 하지 않는 것

3. 주소록 — 8단계 (모두 로그인 필요 — 없으면 401 AUTH_001)

타입

엔드포인트

사내 목록 (/api/directory-entries)

메일과 함께 (2절과 이어지는 것)

173 KiB

Raw Blame History

`POST /api/auth/login`

`GET /api/auth/me`

`POST /api/auth/refresh`

`POST /api/auth/logout`

`PUT /api/auth/password` — 4단계

2. 메일 (모두 로그인 필요 — 없으면 401 `AUTH_001`)

발송 본문 (`POST /api/messages`)

임시 저장 (`/api/drafts`)

서명 (`/api/mail-signature`)

받는 사람 추천 (`/api/recipient-suggestions`)

새 메일 확인 (`/api/mail-state`) — 3단계

검색 (`GET /api/messages` 의 `q`) — 3단계

여러 통 한꺼번에 (`PATCH /api/messages` · `POST /api/message-deletions`) — 3단계

메일함 관리 (`/api/mailboxes`) — 4단계

부재중 자동 응답 (`/api/mail-vacation`) — 4단계

실시간 알림 (`GET /api/mail-events`) — 5단계

메일 필터 (`/api/mail-filters`) — 6단계

이미 받은 메일에 적용 (`/api/mail-filter-runs`) — 7단계

보내기 취소 · 예약 발송 (`POST /api/messages` 의 기다리기 · `/api/scheduled-messages`) — 9단계

외부 이미지 보기 (`images=show` · `/api/mail-images`) — 9단계

보낸 사람 차단 (`/api/mail-blocks`) — 9단계

보내기 · 읽기 설정 (`/api/mail-settings`) — 9단계

3. 주소록 — 8단계 (모두 로그인 필요 — 없으면 401 `AUTH_001`)

사내 목록 (`/api/directory-entries`)