cloud.opencode.base.email.protocol.imap.ImapClient

All Implemented Interfaces:: AutoCloseable

public final class ImapClient extends Object implements AutoCloseable

IMAP4rev1 Protocol Client IMAP4rev1 协议客户端

Implements the IMAP4rev1 protocol (RFC 3501) for mailbox access, message retrieval, folder management, and IDLE push notifications. Supports LOGIN and XOAUTH2 authentication, STARTTLS upgrade, and literal data handling.

实现 IMAP4rev1 协议 (RFC 3501)，支持邮箱访问、邮件检索、文件夹管理和 IDLE 推送通知。支持 LOGIN 和 XOAUTH2 认证、STARTTLS 升级及字面量数据处理。

try (var client = new ImapClient("imap.example.com", 993, true, false,
        Duration.ofSeconds(10), Duration.ofSeconds(30))) {
    client.connect();
    client.login("user@example.com", "password");
    int[] counts = client.select("INBOX");
    System.out.println("Messages: " + counts[0] + ", Recent: " + counts[1]);
    List<Integer> unseen = client.search("UNSEEN");
    for (int seq : unseen) {
        String data = client.fetch(seq, "(ENVELOPE BODY[HEADER])");
        System.out.println(data);
    }
    client.logout();
}

Since:

JDK 25, opencode-base-email V1.0.3

Author:

Leon Soo

See Also:

Constructor Summary

Constructors

Constructor

Description

ImapClient(String host, int port, boolean ssl, boolean starttls, Duration connectionTimeout, Duration readTimeout)

Create a new IMAP client 创建新的 IMAP 客户端
Method Summary

Modifier and Type

Method

Description

void

authenticateXOAuth2(String username, String token)

Authenticate using XOAUTH2 mechanism 使用 XOAUTH2 机制进行认证

void

close()

Close the IMAP client, logging out if connected 关闭 IMAP 客户端，如已连接则先注销

void

connect()

Connect to the IMAP server and read the greeting 连接到 IMAP 服务器并读取问候语

void

copy(int msgSeq, String targetFolder)

Copy a message to another folder 复制邮件到另一个文件夹

int[]

examine(String folder)

Examine a folder for read-only access 以只读方式检查文件夹

void

expunge()

Permanently remove messages marked with \Deleted flag 永久删除标记为 \Deleted 的邮件

String

fetch(int msgSeq, String fetchItems)

Fetch data for a single message 获取单条邮件的数据

Map<Integer,String>

fetchRange(int from, int to, String fetchItems)

Fetch data for a range of messages 获取一系列邮件的数据

Set<String>

getCapabilities()

Get all server capabilities 获取所有服务器能力

int

getMessageCount()

Get the total number of messages in the selected folder 获取所选文件夹中的邮件总数

String

getSelectedFolder()

Get the currently selected folder name 获取当前选中的文件夹名称

int

getUnreadCount()

Get the count of unread (unseen) messages in the selected folder 获取所选文件夹中未读（未查看）邮件的数量

boolean

hasCapability(String cap)

Check if the server advertises the given capability 检查服务器是否公布了给定的能力

List<String>

idle(Duration timeout)

Enter IDLE mode and wait for server notifications 进入 IDLE 模式等待服务器通知

boolean

isConnected()

Check if the client is connected to the server 检查客户端是否已连接到服务器

List<String[]>

list(String reference, String pattern)

List folders matching a pattern 列出匹配模式的文件夹

void

login(String username, String password)

Authenticate using LOGIN command 使用 LOGIN 命令进行认证

void

logout()

Logout from the server and close the connection 从服务器注销并关闭连接

void

noop()

Send NOOP command to keep the connection alive 发送 NOOP 命令以保持连接活跃

List<Integer>

search(String criteria)

Search for messages matching the given criteria 搜索匹配给定条件的邮件

int[]

select(String folder)

Select a folder for read-write access 选择文件夹以读写方式打开

void

store(int msgSeq, String action, String flags)

Store flags on a message 设置邮件的标志

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details
- ImapClient
  
  public ImapClient(String host, int port, boolean ssl, boolean starttls, Duration connectionTimeout, Duration readTimeout)
  
  Create a new IMAP client 创建新的 IMAP 客户端
  
  Parameters:
  
  host - the IMAP server hostname | IMAP 服务器主机名
  
  port - the IMAP server port | IMAP 服务器端口
  
  ssl - true for implicit SSL/TLS (e.g., port 993) | true 使用隐式 SSL/TLS（如 993 端口）
  
  starttls - true to upgrade via STARTTLS after connect | true 连接后通过 STARTTLS 升级
  
  connectionTimeout - connection timeout | 连接超时
  
  readTimeout - read timeout | 读取超时
  
  Throws:
  
  IllegalArgumentException - if host is null/blank, port is invalid, or timeouts are null/negative | 主机为空、端口无效或超时为空/负值时抛出
Method Details
- connect
  
  public void connect() throws ProtocolException
  
  Connect to the IMAP server and read the greeting 连接到 IMAP 服务器并读取问候语
  Connects the underlying socket, reads the server greeting (which must start with * OK), and parses any capabilities advertised in the greeting. If STARTTLS is enabled, upgrades to TLS before proceeding.
  
  连接底层套接字，读取服务器问候语（必须以 * OK 开头），并解析问候语中公布的能力。如果启用了 STARTTLS，则在继续之前升级到 TLS。
  
  Throws:
  
  ProtocolException - if connection or greeting fails | 连接或问候语失败时抛出
- login
  
  public void login(String username, String password) throws ProtocolException
  
  Authenticate using LOGIN command 使用 LOGIN 命令进行认证
  Sends the IMAP LOGIN command with the given username and password. Credentials are quoted according to IMAP string quoting rules.
  
  使用给定的用户名和密码发送 IMAP LOGIN 命令。凭证按照 IMAP 字符串引用规则进行转义。
  
  Parameters:
  
  username - the login username | 登录用户名
  
  password - the login password | 登录密码
  
  Throws:
  
  ProtocolException - if authentication fails | 认证失败时抛出
- authenticateXOAuth2
  public void authenticateXOAuth2(String username, String token) throws ProtocolException
  
  Authenticate using XOAUTH2 mechanism 使用 XOAUTH2 机制进行认证
  Sends the IMAP AUTHENTICATE XOAUTH2 command with a Base64-encoded SASL client response containing the username and OAuth2 bearer token.
  
  使用 Base64 编码的 SASL 客户端响应发送 IMAP AUTHENTICATE XOAUTH2 命令，响应中包含用户名和 OAuth2 Bearer 令牌。
  
  Parameters:
  
  username - the email address | 电子邮件地址
  
  token - the OAuth2 access token | OAuth2 访问令牌
  
  Throws:
  
  ProtocolException - if authentication fails | 认证失败时抛出
  
  See Also:
  
  XOAUTH2
- select
  
  public int[] select(String folder) throws ProtocolException
  
  Select a folder for read-write access 选择文件夹以读写方式打开
  Issues the IMAP SELECT command to open the specified folder for read-write access. Parses EXISTS and RECENT counts from the response.
  
  发出 IMAP SELECT 命令以读写方式打开指定文件夹。从响应中解析 EXISTS 和 RECENT 计数。
  
  Parameters:
  
  folder - the folder name (e.g., "INBOX") | 文件夹名称（如 "INBOX"）
  
  Returns:
  
  an array of [exists, recent] counts | 包含 [exists, recent] 计数的数组
  
  Throws:
  
  ProtocolException - if the SELECT fails | SELECT 失败时抛出
- examine
  
  public int[] examine(String folder) throws ProtocolException
  
  Examine a folder for read-only access 以只读方式检查文件夹
  Issues the IMAP EXAMINE command to open the specified folder for read-only access. Parses EXISTS and RECENT counts from the response.
  
  发出 IMAP EXAMINE 命令以只读方式打开指定文件夹。从响应中解析 EXISTS 和 RECENT 计数。
  
  Parameters:
  
  folder - the folder name (e.g., "INBOX") | 文件夹名称（如 "INBOX"）
  
  Returns:
  
  an array of [exists, recent] counts | 包含 [exists, recent] 计数的数组
  
  Throws:
  
  ProtocolException - if the EXAMINE fails | EXAMINE 失败时抛出
- search
  
  public List<Integer> search(String criteria) throws ProtocolException
  
  Search for messages matching the given criteria 搜索匹配给定条件的邮件
  Issues the IMAP SEARCH command with the specified criteria string. Returns message sequence numbers matching the criteria.
  
  使用指定的条件字符串发出 IMAP SEARCH 命令。返回匹配条件的邮件序列号。
  
  Parameters:
  
  criteria - the IMAP search criteria (e.g., "UNSEEN", "SINCE 1-Jan-2024") | IMAP 搜索条件（如 "UNSEEN"、"SINCE 1-Jan-2024"）
  
  Returns:
  
  a list of message sequence numbers | 邮件序列号列表
  
  Throws:
  
  ProtocolException - if the SEARCH fails | SEARCH 失败时抛出
- fetch
  
  public String fetch(int msgSeq, String fetchItems) throws ProtocolException
  
  Fetch data for a single message 获取单条邮件的数据
  Issues the IMAP FETCH command for the specified message sequence number. Returns the raw response data including any literal content.
  
  对指定的邮件序列号发出 IMAP FETCH 命令。返回原始响应数据，包含字面量内容。
  
  Parameters:
  
  msgSeq - the message sequence number (1-based) | 邮件序列号（从 1 开始）
  
  fetchItems - the fetch data items, e.g., "(ENVELOPE BODY[] FLAGS)" | 获取的数据项，如 "(ENVELOPE BODY[] FLAGS)"
  
  Returns:
  
  the raw FETCH response data | 原始 FETCH 响应数据
  
  Throws:
  
  ProtocolException - if the FETCH fails | FETCH 失败时抛出
- fetchRange
  
  public Map<Integer,String> fetchRange(int from, int to, String fetchItems) throws ProtocolException
  
  Fetch data for a range of messages 获取一系列邮件的数据
  Issues a single IMAP FETCH command for a range of message sequence numbers. Returns a map from sequence number to the raw response data for that message.
  
  对一系列邮件序列号发出单个 IMAP FETCH 命令。返回序列号到该邮件原始响应数据的映射。
  
  Parameters:
  
  from - the starting sequence number (inclusive) | 起始序列号（包含）
  
  to - the ending sequence number (inclusive) | 结束序列号（包含）
  
  fetchItems - the fetch data items | 获取的数据项
  
  Returns:
  
  a map of sequence number to raw response data | 序列号到原始响应数据的映射
  
  Throws:
  
  ProtocolException - if the FETCH fails | FETCH 失败时抛出
- store
  
  public void store(int msgSeq, String action, String flags) throws ProtocolException
  
  Store flags on a message 设置邮件的标志
  Issues the IMAP STORE command to modify flags on the specified message.
  
  发出 IMAP STORE 命令以修改指定邮件的标志。
  
  Parameters:
  
  msgSeq - the message sequence number (1-based) | 邮件序列号（从 1 开始）
  
  action - the flag action: "+FLAGS", "-FLAGS", or "FLAGS" | 标志操作："+FLAGS"、"-FLAGS" 或 "FLAGS"
  
  flags - the flags, e.g., "(\\Seen)" or "(\\Deleted)" | 标志，如 "(\\Seen)" 或 "(\\Deleted)"
  
  Throws:
  
  ProtocolException - if the STORE fails | STORE 失败时抛出
- copy
  
  public void copy(int msgSeq, String targetFolder) throws ProtocolException
  
  Copy a message to another folder 复制邮件到另一个文件夹
  Issues the IMAP COPY command to copy the specified message to the target folder.
  
  发出 IMAP COPY 命令将指定邮件复制到目标文件夹。
  
  Parameters:
  
  msgSeq - the message sequence number (1-based) | 邮件序列号（从 1 开始）
  
  targetFolder - the destination folder name | 目标文件夹名称
  
  Throws:
  
  ProtocolException - if the COPY fails | COPY 失败时抛出
- expunge
  
  public void expunge() throws ProtocolException
  
  Permanently remove messages marked with \Deleted flag 永久删除标记为 \Deleted 的邮件
  Issues the IMAP EXPUNGE command to permanently remove all messages in the selected folder that have the \Deleted flag set.
  
  发出 IMAP EXPUNGE 命令以永久删除所选文件夹中设置了 \Deleted 标志的所有邮件。
  
  Throws:
  
  ProtocolException - if the EXPUNGE fails | EXPUNGE 失败时抛出
- list
  
  public List<String[]> list(String reference, String pattern) throws ProtocolException
  
  List folders matching a pattern 列出匹配模式的文件夹
  Issues the IMAP LIST command to list folders matching the given reference and pattern. Returns each folder as a [flags, delimiter, name] array.
  
  发出 IMAP LIST 命令列出匹配给定引用和模式的文件夹。每个文件夹以 [flags, delimiter, name] 数组形式返回。
  
  Parameters:
  
  reference - the reference name (e.g., "" for root) | 引用名（如 "" 表示根目录）
  
  pattern - the folder pattern (e.g., "*" for all) | 文件夹模式（如 "*" 表示全部）
  
  Returns:
  
  a list of [flags, delimiter, name] arrays | [flags, delimiter, name] 数组列表
  
  Throws:
  
  ProtocolException - if the LIST fails | LIST 失败时抛出
- idle
  
  public List<String> idle(Duration timeout) throws ProtocolException
  
  Enter IDLE mode and wait for server notifications 进入 IDLE 模式等待服务器通知
  Issues the IMAP IDLE command to enter push notification mode. Blocks until the server sends untagged responses (e.g., new mail notifications) or the specified timeout is reached. Automatically sends DONE to exit IDLE mode before returning.
  
  发出 IMAP IDLE 命令进入推送通知模式。阻塞直到服务器发送未标记响应（如新邮件通知）或达到指定超时时间。返回前自动发送 DONE 以退出 IDLE 模式。
  
  Parameters:
  
  timeout - the maximum time to remain in IDLE mode | IDLE 模式的最大等待时间
  
  Returns:
  
  the untagged responses received during IDLE | IDLE 期间接收到的未标记响应
  
  Throws:
  
  ProtocolException - if IDLE is not supported or fails | 不支持 IDLE 或失败时抛出
- noop
  
  public void noop() throws ProtocolException
  
  Send NOOP command to keep the connection alive 发送 NOOP 命令以保持连接活跃
  Issues the IMAP NOOP command which has no effect on the server state but resets idle timers and may trigger pending untagged notifications.
  
  发出 IMAP NOOP 命令，该命令不影响服务器状态，但会重置空闲计时器并可能触发待处理的未标记通知。
  
  Throws:
  
  ProtocolException - if the NOOP fails | NOOP 失败时抛出
- getMessageCount
  
  public int getMessageCount() throws ProtocolException
  
  Get the total number of messages in the selected folder 获取所选文件夹中的邮件总数
  Issues a STATUS command on the currently selected folder to retrieve the MESSAGES count.
  
  对当前选中的文件夹发出 STATUS 命令以获取 MESSAGES 计数。
  
  Returns:
  
  the message count | 邮件数量
  
  Throws:
  
  ProtocolException - if the command fails | 命令失败时抛出
- getUnreadCount
  
  public int getUnreadCount() throws ProtocolException
  
  Get the count of unread (unseen) messages in the selected folder 获取所选文件夹中未读（未查看）邮件的数量
  Issues a SEARCH UNSEEN command and returns the count of matching message sequence numbers.
  
  发出 SEARCH UNSEEN 命令并返回匹配的邮件序列号数量。
  
  Returns:
  
  the unread message count | 未读邮件数量
  
  Throws:
  
  ProtocolException - if the SEARCH fails | SEARCH 失败时抛出
- logout
  
  public void logout() throws ProtocolException
  
  Logout from the server and close the connection 从服务器注销并关闭连接
  Issues the IMAP LOGOUT command, reads the BYE response, and closes the underlying socket connection.
  
  发出 IMAP LOGOUT 命令，读取 BYE 响应，并关闭底层套接字连接。
  
  Throws:
  
  ProtocolException - if the LOGOUT fails | LOGOUT 失败时抛出
- close
  
  public void close()
  
  Close the IMAP client, logging out if connected 关闭 IMAP 客户端，如已连接则先注销
  Attempts a graceful LOGOUT before closing the connection. Any errors during logout are silently ignored.
  
  在关闭连接前尝试正常注销。注销过程中的任何错误将被静默忽略。
  
  Specified by:
  
  close in interface AutoCloseable
- hasCapability
  
  public boolean hasCapability(String cap)
  
  Check if the server advertises the given capability 检查服务器是否公布了给定的能力
  
  Parameters:
  
  cap - the capability name (case-insensitive) | 能力名称（不区分大小写）
  
  Returns:
  
  true if the capability is present | 如果存在该能力返回 true
- getCapabilities
  
  public Set<String> getCapabilities()
  
  Get all server capabilities 获取所有服务器能力
  
  Returns:
  
  an unmodifiable set of capability names (uppercase) | 能力名称的不可修改集合（大写）
- isConnected
  
  public boolean isConnected()
  
  Check if the client is connected to the server 检查客户端是否已连接到服务器
  
  Returns:
  
  true if connected | 已连接返回 true
- getSelectedFolder
  
  public String getSelectedFolder()
  
  Get the currently selected folder name 获取当前选中的文件夹名称
  
  Returns:
  
  the selected folder name, or null if none is selected | 选中的文件夹名称，未选中则返回 null

Class ImapClient

Constructor Summary

Method Summary

Methods inherited from class Object

Constructor Details

ImapClient

Method Details

connect

login

authenticateXOAuth2

select

examine

search

fetch

fetchRange

store

copy

expunge

list

idle

noop

getMessageCount

getUnreadCount

logout

close

hasCapability

getCapabilities

isConnected

getSelectedFolder