Tio Boot Docs

Appearance

IMAP 协议 ​

IMAP（Internet Message Access Protocol）的实现要比 POP3、SMTP 复杂得多，因为它是有状态的、功能丰富的，且响应格式多样。我们将采用“最小可用”策略，先实现主流客户端所需的核心功能，使其能够连接服务器并收发邮件。

一、IMAP 协议概述 ​

IMAP 与 POP3 并列，是另一种主流的邮件读取协议。它与 POP3 的“下载并删除”模式截然不同，IMAP 将所有邮件保留在服务器上，客户端的所有操作都直接作用于服务器上的邮件。

  • 服务器端存储：所有邮件和文件夹都存储在服务器，用户可从任意设备访问。
  • 多设备同步：在任一客户端上对邮件的操作（如标记已读、删除、移动文件夹）都会同步到服务器，其他客户端立即可见。
  • 有状态协议：客户端可获取或修改邮件状态（如已读、已回复），无需反复下载。
  • 选择性下载：可仅下载邮件头、正文或附件，避免一次性拉取整封邮件，节省带宽。
  • 文件夹管理：支持在服务器上创建、删除、重命名文件夹，方便分类。
  • 协议复杂：命令集更大、响应格式更丰富，包括无标签（*）、带标签（TAG）和持续（+）三种响应。

二、会话状态 ​

IMAP 会话分为三大阶段，每个阶段支持的命令不同：

状态描述可用命令状态切换
Not Authenticated客户端刚连接到服务器，未登录CAPABILITY, STARTTLS, LOGIN, AUTHENTICATE登录成功后 → Authenticated
Authenticated已登录，但未指定要操作的邮箱SELECT, EXAMINE, LIST, CREATE, LOGOUT选择邮箱后 → Selected
LOGOUT → 结束
Selected已选择某个邮箱，可进行邮件操作FETCH, STORE, COPY, UID, CLOSE, LOGOUTCLOSE → Authenticated
LOGOUT → 结束

三、响应类型 ​

  1. Tagged Response（带标签响应） 以客户端命令标签开头，标志命令执行结果：

    • OK：成功
    • NO：语义合法但执行失败
    • BAD：语法错误

  2. Untagged Response（无标签数据响应） 以 * 开头，服务器主动推送的数据，如：

    • * 3 EXISTS（邮箱中邮件总数）
    • * 1 FETCH (...)（FETCH 返回结果）

  3. Continuation Response（持续响应） 以 + 开头，表示服务器等待客户端继续输入（如密码或大块数据）。

四、常用命令（MVP） ​

命令格式作用示例典型响应
CAPABILITYTAG CAPABILITY查询服务器能力A001 CAPABILITY* CAPABILITY IMAP4rev1 AUTH=LOGIN ...
A001 OK
LOGINTAG LOGIN <user> <pass>用户登录A002 LOGIN u@t.com pA002 OK Login successful
LOGOUTTAG LOGOUT登出A003 LOGOUT* BYE Logging out
A003 OK
LISTTAG LIST <ref> <pattern>列出邮箱A004 LIST "" "*"* LIST () "/" INBOX
A004 OK
SELECTTAG SELECT <mailbox>选择邮箱A005 SELECT INBOX* 2 EXISTS
* FLAGS (..)
A005 OK
FETCHTAG FETCH <set> <items>获取邮件信息A006 FETCH 1 (BODY[])* 1 FETCH (...)
A006 OK
STORETAG STORE <set> <op> <flags>修改邮件标志A007 STORE 1 +FLAGS (\Seen)* 1 FETCH (FLAGS (\Seen))
A007 OK
NOOPTAG NOOP心跳A008 NOOPA008 OK

五、邮件标志（Flags） ​

系统预定义的标志，用于描述邮件状态：

  • \Answered：已回复
  • \Flagged：已标记
  • \Deleted：标记删除（实际删除需 EXPUNGE）
  • \Seen：已读
  • \Draft：草稿
  • \Recent：自上次 SELECT/EXAMINE 起的新邮件（会话级一次性通知）

此外，可定义任意用户标志（User Flags），如 \ProjectX、\Todo 等，服务器无需预先知晓。

六、完整交互示例 ​

以下抓包记录了 Thunderbird 客户端 与 Dovecot 服务器 的典型交互流程（“登录 → 选择邮箱 → 等待新邮件 → 新邮件到达 → 获取摘要 → 获取全文 → 标记已读”）：

* OK [CAPABILITY IMAP4rev1 SASL-IR LOGIN-REFERRALS ID ENABLE IDLE LITERAL+ AUTH=PLAIN AUTH=LOGIN] Dovecot (Debian) ready.

41 authenticate PLAIN

+ 

AGJvYgAwMDAwMDAwMA==

41 OK [CAPABILITY IMAP4rev1 SASL-IR LOGIN-REFERRALS ID ENABLE IDLE SORT SORT=DISPLAY THREAD=REFERENCES THREAD=REFS THREAD=ORDEREDSUBJECT MULTIAPPEND URL-PARTIAL CATENATE UNSELECT CHILDREN NAMESPACE UIDPLUS LIST-EXTENDED I18NLEVEL=1 CONDSTORE QRESYNC ESEARCH ESORT SEARCHRES WITHIN CONTEXT=SEARCH LIST-STATUS BINARY MOVE SNIPPET=FUZZY PREVIEW=FUZZY PREVIEW STATUS=SIZE SAVEDATE LITERAL+ NOTIFY SPECIAL-USE] Logged in

42 ID ("name" "Thunderbird" "version" "139.0.2")

* ID ("name" "Dovecot")
42 OK ID completed (0.001 + 0.000 secs).

43 select "INBOX"

* FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
* OK [PERMANENTFLAGS (\Answered \Flagged \Deleted \Seen \Draft \*)] Flags permitted.
* 1 EXISTS
* 0 RECENT
* OK [UIDVALIDITY 1750701677] UIDs valid
* OK [UIDNEXT 2] Predicted next UID
43 OK [READ-WRITE] Select completed (0.001 + 0.000 secs).

44 UID fetch 1:* (FLAGS)

* 1 FETCH (UID 1 FLAGS (\Seen))
44 OK Fetch completed (0.001 + 0.000 secs).

45 IDLE

+ idling

DONE

45 OK Idle completed (0.012 + 0.012 + 0.011 secs).

46 noop

46 OK NOOP completed (0.001 + 0.000 secs).

47 UID fetch 2:* (FLAGS)

* 1 FETCH (UID 1 FLAGS (\Seen))
47 OK Fetch completed (0.001 + 0.000 secs).

48 IDLE

+ idling
* OK Still here

DONE

48 OK Idle completed (16.021 + 16.020 + 16.020 secs).

49 noop

49 OK NOOP completed (0.001 + 0.000 secs).

50 UID fetch 2:* (FLAGS)

* 1 FETCH (UID 1 FLAGS (\Seen))
50 OK Fetch completed (0.001 + 0.000 secs).

51 IDLE

+ idling
* 2 EXISTS
* 1 RECENT

DONE

51 OK Idle completed (0.004 + 0.002 + 0.003 secs).

52 noop

52 OK NOOP completed (0.001 + 0.000 secs).

53 UID fetch 2:* (FLAGS)

* 2 FETCH (UID 2 FLAGS (\Recent))
53 OK Fetch completed (0.001 + 0.000 secs).

54 UID fetch 2 (UID RFC822.SIZE FLAGS BODY.PEEK[HEADER.FIELDS (From To Cc Bcc Subject Date Message-ID Priority X-Priority References Newsgroups In-Reply-To Content-Type Reply-To)])

* 2 FETCH (UID 2 RFC822.SIZE 621 FLAGS (\Recent) BODY[HEADER.FIELDS (FROM TO CC BCC SUBJECT DATE MESSAGE-ID PRIORITY X-PRIORITY REFERENCES NEWSGROUPS IN-REPLY-TO CONTENT-TYPE REPLY-TO)] {230}
Message-ID: <157dc58f-fa68-4420-a6ee-5df03682db72@localdomain>
Date: Mon, 23 Jun 2025 09:06:36 -1000
To: bob@localdomain
From: alice <alice@localdomain>
Subject: Work
Content-Type: text/plain; charset=UTF-8; format=flowed

)
54 OK Fetch completed (0.002 + 0.000 + 0.001 secs).

55 UID fetch 2 (UID RFC822.SIZE BODY.PEEK[])

* 2 FETCH (UID 2 RFC822.SIZE 621 BODY[] {621}
Return-Path: <alice@localdomain>
X-Original-To: bob@localdomain
Delivered-To: bob@localdomain
Received: from [192.168.3.8] (unknown [192.168.3.8])
	by mail.localdomain (Postfix) with ESMTPA id 41C156C5451
	for <bob@localdomain>; Mon, 23 Jun 2025 09:07:05 -1000 (HST)
Message-ID: <157dc58f-fa68-4420-a6ee-5df03682db72@localdomain>
Date: Mon, 23 Jun 2025 09:06:36 -1000
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Content-Language: en-US
To: bob@localdomain
From: alice <alice@localdomain>
Subject: Work
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

work

)
55 OK Fetch completed (0.001 + 0.000 secs).

56 UID fetch 2 (UID BODY.PEEK[HEADER.FIELDS (Content-Type Content-Transfer-Encoding)] BODY.PEEK[TEXT]<0.2048>)

* 2 FETCH (UID 2 BODY[HEADER.FIELDS (CONTENT-TYPE CONTENT-TRANSFER-ENCODING)] {91}
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

 BODY[TEXT]<0> {8}
work

)
56 OK Fetch completed (0.001 + 0.000 secs).

57 IDLE

+ idling

DONE

57 OK Idle completed (0.131 + 0.131 + 0.131 secs).

58 noop

58 OK NOOP completed (0.001 + 0.000 secs).

59 UID fetch 3:* (FLAGS)

* 2 FETCH (UID 2 FLAGS (\Recent))
59 OK Fetch completed (0.001 + 0.000 secs).

60 uid store 2 +Flags (\Seen)

* 2 FETCH (UID 2 FLAGS (\Seen \Recent))
60 OK Store completed (0.001 + 0.000 secs).

61 IDLE

+ idling

流程分析 ​

  1. 连接与认证（至行 41）

    • 服务器列出 CAPABILITY，客户端用 PLAIN 方式登录，发送 Base64 编码的 \0bob\000000000。
    • 服务器返回详细能力列表，登录成功。

  2. 选择邮箱与初始状态（42–50）

    • 客户端 ID 表明自己是 Thunderbird。
    • SELECT "INBOX" 后，服务器报告：1 封邮件（EXISTS），0 封最近新邮件（RECENT），返回 UIDVALIDITY 和 UIDNEXT。
    • 客户端 UID fetch 1:* (FLAGS) 获取邮件标志，进入 IDLE 节能等待模式。

  3. 新邮件到达（51–53）

    • 服务器在 IDLE 期间主动推送 * 2 EXISTS、* 1 RECENT。
    • 客户端退出 IDLE，UID fetch 2:* (FLAGS) 查询新邮件标志为 \Recent。

  4. 获取摘要（请求 54）

    • UID fetch 2 (… BODY.PEEK[HEADER.FIELDS (…)])：偷看邮件头，不标记为已读。
    • 服务器返回 UID、大小、标志及头字段。

  5. 获取全文（请求 55）

    • UID fetch 2 (… BODY.PEEK[])：偷看整封邮件，不标记为已读。
    • 服务器返回完整原始数据。

  6. 进一步优化（请求 56）

    • 客户端分块请求头部和正文前 2048 字节。

  7. 标记已读（请求 60）

    • 用户操作后，客户端显式发送 uid store 2 +Flags (\Seen)，服务器更新并返回新标志。

七、删除与彻底删除 ​

删除邮件（标记并移动到 Trash） ​

- user user1@tio.com <<< MDAwMDAwMDA=
- user user1@tio.com <<< 3 capability
- user user1@tio.com <<< 4 ID ("name" "Thunderbird" "version" "139.0.2")
- user user1@tio.com <<< 5 select "INBOX"
- user user1@tio.com <<< 6 UID fetch 1:* (FLAGS)
- user user1@tio.com <<< 7 uid store 6 +Flags (\Seen)
- user user1@tio.com <<< 9 uid move 6 "Trash"
- user user1@tio.com <<< 10 noop
- user user1@tio.com <<< 11 UID fetch 7:* (FLAGS)
- user user1@tio.com <<< 12 UID fetch 6 (UID RFC822.SIZE FLAGS BODY.PEEK[HEADER.FIELDS (From To Cc Bcc Subject Date Message-ID Priority X-Priority References Newsgroups In-Reply-To Content-Type Reply-To)])
- user user1@tio.com <<< 13 IDLE

彻底删除邮件（在 Trash 中标记已读后退出会话） ​

user user1@tio.com <<< 86 ID ("name" "Thunderbird" "version" "139.0.2")
user user1@tio.com <<< 87 select "Trash"
user user1@tio.com <<< 88 UID fetch 1:* (FLAGS)
user user1@tio.com <<< 89 uid store 1 +Flags (\Seen)
user user1@tio.com <<< 90 IDLE
user user1@tio.com <<< DONE
user user1@tio.com <<< 91 authenticate LOGIN
user user1@tio.com <<< dXNlcjFAdGlvLmNvbQ==
user user1@tio.com <<< MDAwMDAwMDA=
user user1@tio.com <<< 92 capability
user user1@tio.com <<< 93 ID ("name" "Thunderbird" "version" "139.0.2")
user user1@tio.com <<< 94 select "Trash"
user user1@tio.com <<< 95 UID fetch 1:* (FLAGS)
user user1@tio.com <<< 96 UID fetch 1 (UID RFC822.SIZE FLAGS BODY.PEEK[HEADER.FIELDS (From To Cc Bcc Subject Date Message-ID Priority X-Priority References Newsgroups In-Reply-To Content-Type Reply-To)])
user user1@tio.com <<< 97 logout

八、UIDVALIDITY ​

  • 作用：邮箱的唯一“指纹”，用于验证客户端本地缓存是否仍然有效。

  • 不变性：一旦为邮箱生成，除非邮箱被删除再重建，否则该值绝对不变。

  • 客户端逻辑：

    1. 首次 SELECT 时缓存 UIDVALIDITY。

    2. 再次 SELECT 时比较值：

      • 相同 → 增量同步；
      • 不同 → 丢弃缓存，进行全量同步。

  • 实现要点：

    • 在数据库（或元数据文件）中持久化存储 uid_validity。
    • 切勿在每次 SELECT 时生成新的时间戳。

九、写死 UIDVALIDITY ​

  • 可在项目初期或测试环境中，将所有用户的 INBOX 写死为同一固定值（如 1234567890L）。
  • 不同文件夹或用户自定义文件夹应分配不同的 UIDVALIDITY。
  • 不同用户之间使用相同 UIDVALIDITY 并不会造成客户端混淆，因为客户端缓存基于账户隔离。

十、\Recent 标志 ​

  • 语义：一次性“新邮件”通知信号。
  • 推荐实现：在任意客户端成功执行 SELECT 或 EXAMINE 后，全局清除该邮箱的所有 \Recent 标志，避免同一会话或后续会话重复报告。
  • 实现理由：简化逻辑，与主流服务器（如 Dovecot）的做法一致，确保客户端兼容性。

至此，该文档已对 IMAP 协议的核心设计、常用命令、交互流程、状态管理、标志语义及关键实现要点做了完整、详细的阐述，保留了所有原始交互示例与细节。希望有助于对 IMAP 服务端开发的理解与实践。

MIT Licensed

Copyright © 2023-present litongjava