Class SmtpClient

java.lang.Object

cloud.opencode.base.email.protocol.smtp.SmtpClient

All Implemented Interfaces:

AutoCloseable

public final class SmtpClient
extends Object
implements AutoCloseable

SMTP Protocol Client (RFC 5321) SMTP协议客户端（RFC 5321）

Implements the Simple Mail Transfer Protocol for sending emails. Supports PLAIN, LOGIN, and XOAUTH2 authentication mechanisms, STARTTLS upgrade, and transparent dot-stuffing for message data.

实现简单邮件传输协议用于发送电子邮件。 支持PLAIN、LOGIN和XOAUTH2认证机制、STARTTLS升级以及消息数据的透明点填充。

This class is not thread-safe. Each instance manages a single SMTP connection and should be used by one thread at a time.

此类非线程安全。每个实例管理单个SMTP连接，应在同一时间仅由一个线程使用。

Since:

JDK 25, opencode-base-email V1.0.3

Author:

Leon Soo

See Also:

• MailConnection
• OpenCode.cloud

Constructor Summary

Constructors

Constructor	Description
SmtpClient(String host, int port, boolean ssl, boolean starttls, Duration connectionTimeout, Duration readTimeout)	Create a new SMTP client 创建新的SMTP客户端

Method Summary

Modifier and Type	Method	Description
void	authLogin(String username, String password)	Authenticate using the LOGIN mechanism 使用LOGIN机制认证
void	authPlain(String username, String password)	Authenticate using the PLAIN mechanism (RFC 4616) 使用PLAIN机制认证（RFC 4616）
void	authXOAuth2(String username, String token)	Authenticate using the XOAUTH2 mechanism (for Gmail/Outlook) 使用XOAUTH2机制认证（适用于Gmail/Outlook）
void	close()	Close the connection, ignoring any errors 关闭连接，忽略任何错误
String	connect()	Connect to the SMTP server and perform the EHLO handshake 连接到SMTP服务器并执行EHLO握手
Set<String>	getCapabilities()	Get the server capabilities parsed from the EHLO response 获取从EHLO响应中解析的服务器能力集
boolean	hasCapability(String capability)	Check if the server supports a specific capability 检查服务器是否支持指定能力
boolean	isConnected()	Check if the underlying connection is active 检查底层连接是否活跃
void	quit()	Send QUIT command and close the connection 发送QUIT命令并关闭连接
void	sendMessage(String sender, List<String> recipients, String rawMessage)	Send a complete email message 发送完整的电子邮件

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SmtpClient

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

Create a new SMTP client 创建新的SMTP客户端

Parameters:

host - the SMTP server hostname | SMTP服务器主机名

port - the SMTP server port | SMTP服务器端口

ssl - true for implicit SSL/TLS connection | true使用隐式SSL/TLS连接

starttls - true to upgrade via STARTTLS after connecting | true连接后通过STARTTLS升级

connectionTimeout - connection timeout | 连接超时

readTimeout - read timeout | 读取超时

Method Details

connect

public String connect()
               throws ProtocolException

Connect to the SMTP server and perform the EHLO handshake 连接到SMTP服务器并执行EHLO握手

Establishes the connection, reads the server greeting, sends EHLO, and optionally upgrades to TLS via STARTTLS.

建立连接，读取服务器问候语，发送EHLO，并可选地通过STARTTLS升级到TLS。

Returns:

the server greeting string | 服务器问候字符串

Throws:

ProtocolException - if connection or handshake fails | 连接或握手失败时抛出

authPlain

public void authPlain(String username,
 String password)
               throws ProtocolException

Authenticate using the PLAIN mechanism (RFC 4616) 使用PLAIN机制认证（RFC 4616）

Parameters:

username - the username | 用户名

password - the password | 密码

Throws:

ProtocolException - if authentication fails | 认证失败时抛出

authLogin

public void authLogin(String username,
 String password)
               throws ProtocolException

Authenticate using the LOGIN mechanism 使用LOGIN机制认证

Parameters:

username - the username | 用户名

password - the password | 密码

Throws:

ProtocolException - if authentication fails | 认证失败时抛出

authXOAuth2

public void authXOAuth2(String username,
 String token)
                 throws ProtocolException

Authenticate using the XOAUTH2 mechanism (for Gmail/Outlook) 使用XOAUTH2机制认证（适用于Gmail/Outlook）

Parameters:

username - the email address | 邮箱地址

token - the OAuth2 access token | OAuth2访问令牌

Throws:

ProtocolException - if authentication fails | 认证失败时抛出

sendMessage

public void sendMessage(String sender,
 List<String> recipients,
 String rawMessage)
                 throws ProtocolException

Send a complete email message 发送完整的电子邮件

Performs the MAIL FROM, RCPT TO, and DATA sequence. The rawMessage must be a complete RFC 2822 formatted message. Lines starting with "." are transparently dot-stuffed per RFC 5321 Section 4.5.2.

执行MAIL FROM、RCPT TO和DATA序列。 rawMessage必须是完整的RFC 2822格式消息。 以"."开头的行会根据RFC 5321第4.5.2节进行透明点填充。

Parameters:

sender - the envelope sender address (MAIL FROM) | 信封发件人地址

recipients - all envelope recipient addresses (RCPT TO) | 所有信封收件人地址

rawMessage - the complete RFC 2822 message | 完整的RFC 2822消息

Throws:

ProtocolException - if sending fails | 发送失败时抛出

isConnected

public boolean isConnected()

Check if the underlying connection is active 检查底层连接是否活跃

Returns:

true if connected | 已连接返回true

quit

public void quit()
          throws ProtocolException

Send QUIT command and close the connection 发送QUIT命令并关闭连接

Throws:

ProtocolException - if the QUIT exchange fails | QUIT交换失败时抛出

close

public void close()

Close the connection, ignoring any errors 关闭连接，忽略任何错误

Specified by:

close in interface AutoCloseable

getCapabilities

public Set<String> getCapabilities()

Get the server capabilities parsed from the EHLO response 获取从EHLO响应中解析的服务器能力集

Returns:

unmodifiable set of capability strings | 不可修改的能力字符串集合

hasCapability

public boolean hasCapability(String capability)

Check if the server supports a specific capability 检查服务器是否支持指定能力

Matching is case-insensitive and checks only the first token of each capability line (e.g., "AUTH" matches "AUTH PLAIN LOGIN").

匹配不区分大小写，仅检查每个能力行的第一个令牌 （例如，"AUTH"匹配"AUTH PLAIN LOGIN"）。

Parameters:

capability - the capability to check (e.g., "STARTTLS", "AUTH") | 要检查的能力

Returns:

true if the server advertises the capability | 服务器公布该能力返回true