Jakarta Java Mail属性参数配置

前言

Jakarta Mail网址：https://eclipse-ee4j.github.io/mail

SMTP协议可匹配的属性：https://eclipse-ee4j.github.io/mail/docs/api/com/sun/mail/smtp/package-summary.html

翻译(Package com.sun.mail.smtp)

Package com.sun.mail.smtp

Jakarta Mail API的SMTP协议提供程序，提供对SMTP服务器的访问。

Class Summary

• SMTPMessage 此类是MimeMessage类的特殊化，它允许您指定通过SMTP发送此消息时将使用的各种SMTP选项和参数。
• SMTPSSLTransport 此类使用SSL上的SMTP实现SMTP传输抽象类，以进行邮件提交和传输。
• SMTPTransport 此类使用SMTP实现Transport抽象类，以进行邮件提交和传输。

Exception Summary

• SMTPAddressFailedException 无法发送消息时，抛出此异常。
• SMTPAddressSucceededException 当mail.smtp.reportsuccess属性为true时，此异常将链接到SendFailedException。
• SMTPSenderFailedException 无法发送消息时，抛出此异常。
• SMTPSendFailedException 无法发送消息时，抛出此异常。

Package com.sun.mail.smtp Description

Jakarta Mail API的SMTP协议提供程序，提供对SMTP服务器的访问。有关更多信息，请参考RFC 821。

发送消息时，在抛出的顶级SendFailedException链接的SMTPAddressFailedException中提供了有关每个失败地址的详细信息。 此外，如果设置了mail.smtp.reportsuccess属性，则对于每个成功地址，SMTPAddressSucceededException将包括在列表中。 请注意，即使发送成功，这也会导致抛出顶级SendFailedException。

SMTP提供程序还支持ESMTP（RFC 1651）。它可以选择使用LOGIN，PLAIN，DIGEST-MD5和NTLM机制（RFC 4616和RFC 2831）使用SMTP身份验证（RFC 2554）。

要使用SMTP身份验证，您需要设置mail.smtp.auth属性（请参见下文）或在连接到SMTP服务器时为SMTP传输提供用户名和密码。您可以使用以下方法之一来执行此操作：

• 在创建邮件Session时提供Authenticator对象，并在Authenticator回调过程中提供用户名和密码信息。

请注意，可以将mail.smtp.user属性设置为为回调提供默认用户名，但是仍然需要显式提供密码。这种方法允许您使用静态传输发送方法来发送消息。

• 使用用户名和密码参数显式调用Transport connect方法。

此方法要求您显式管理传输对象，并使用传输sendMessage方法发送消息。 transport.java演示程序演示了如何管理Transport对象。 以下内容大致等同于静态Transport send方法，但提供了所需的用户名和密码：

Transport tr = session.getTransport("smtp");
tr.connect(smtphost, username, password);
msg.saveChanges();      // don't forget this
tr.sendMessage(msg, msg.getAllRecipients());
tr.close();

使用DIGEST-MD5身份验证时，您还需要提供适当的领域(realm)；您的邮件服务器管理员可以提供此信息。您可以使用mail.smtp.sasl.realm属性或SMTPTransport上的setSASLRealm方法进行设置。

SMTP协议提供程序可以在支持javax.security.sasl API（例如J2SE 5.0）的系统上使用SASL（RFC 2222）身份验证机制。 除了内置于SASL实现中的SASL机制之外，用户还可以提供自己设计的其他SASL机制，以支持自定义身份验证方案。 有关详细信息，请参见《 Java SASL API编程和部署指南》。 请注意，当前的实现不支持提供自己的完整性或机密性层的SASL机制。

通过上述的SASL支持或作为SMTP提供程序中的内置身份验证机制，可以通过XOAUTH2身份验证机制支持OAuth 2.0身份验证。 OAuth 2.0访问令牌应作为此机制的密码传递。 有关详细信息，请参见OAuth2支持。

SMTP还可以选择请求传递状态通知（RFC 1891）。 通常使用带有“message/delivery-status”（RFC 1894）部分的“multipart/report”（RFC 1892）消息类型报告传递状态。 您可以使用com.sun.mail.dsn包中的类来处理这些MIME类型。 请注意，您需要在CLASSPATH中包含dsn.jar，因为mail.jar中不包含此支持。

请参阅以下有关启用这些功能的属性。

还请注意，这里没有足够的文档来使用这些功能！！！ 您将需要阅读上述适当的RFC，以了解这些功能的作用以及如何使用它们。 不要只是开始设置属性，然后在无法正常运行时向我们投诉，就像您期望的那样。 首先阅读RFC ！！！

SMTP协议提供程序支持RFC 3030中定义的CHUNKING扩展。将mail.smtp.chunksize属性设置为所需的块大小（以字节为单位）。 如果服务器支持CHUNKING扩展，则将使用BDAT命令以块大小发送消息。 请注意，没有流水线(pipelining )操作，因此这比发送消息慢得多。 另请注意，不支持RFC 3030中描述的BINARYMIME扩展。

Properties

SMTP协议提供程序支持以下属性，可以在Jakarta Mail Session对象中设置这些属性。这些属性始终设置为字符串。 “类型”列描述了如何解释字符串。例如使用

props.put("mail.smtp.port", "888");

设置类型为int的mail.smtp.port属性。

请注意，如果您使用“smtps”协议通过SSL访问SMTP，则所有属性都将命名为 "mail.smtps.*" 。

SMTP properties

Name	Type	Description
mail.smtp.user	String	SMTP的默认用户名。
mail.smtp.host	String	要连接的SMTP服务器。
mail.smtp.port	int	如果 connect()方法未明确指定一个，则要连接的SMTP服务器端口。默认为25。
mail.smtp.connectiontimeout	int	套接字连接超时值（以毫秒为单位）。此超时由java.net.Socket实现。默认值为无限超时。
mail.smtp.timeout	int	套接字读取超时值（以毫秒为单位）。此超时由java.net.Socket实现。默认值为无限超时。
mail.smtp.writetimeout	int	套接字写入超时值（以毫秒为单位）。 此超时是通过每个连接使用java.util.concurrent.ScheduledExecutorService来实现的，该连接计划在超时后调度线程以关闭套接字。 因此，使用此超时的开销是每个连接一个线程。 默认值为无限超时。
mail.smtp.from	String	SMTP MAIL命令使用的电子邮件地址。设置信封的返回地址。默认为 msg.getFrom() 或 InternetAddress.getLocalAddress() 。注意：以前曾使用过mail.smtp.user。
mail.smtp.localhost	String	SMTP HELO或EHLO命令中使用的本地主机名。默认为 InetAddress.getLocalHost().getHostName() 。如果您的JDK和名称服务配置正确，通常不需要设置。
mail.smtp.localaddress	String	创建SMTP套接字时要绑定的本地地址（主机名）。 默认为Socket class选择的地址。 通常不需要设置，但对于选择特定本地地址进行绑定的multi-homed主主机很有用。
mail.smtp.localport	int	创建SMTP套接字时要绑定的本地端口号。默认为Socket类选择的端口号。
mail.smtp.ehlo	boolean	如果为false，则不要尝试使用EHLO命令登录。 默认为true。 通常，EHLO命令的失败将回退到HELO命令。 此属性仅适用于未正确使EHLO失败或未正确实现EHLO的服务器。
mail.smtp.auth	boolean	如果为true，请尝试使用AUTH命令对用户进行身份验证。默认为false。
mail.smtp.auth.mechanisms	String	如果已设置，则列出要考虑的身份验证机制以及考虑它们的顺序。 仅使用服务器支持和当前实现支持的机制。 默认值为“LOGIN PLAIN DIGEST-MD5 NTLM”，其中包括当前实现（除XOAUTH2之外）支持的所有身份验证机制。
mail.smtp.auth.login.disable	boolean	如果为true，则禁止使用AUTH LOGIN命令。默认为false。
mail.smtp.auth.plain.disable	boolean	如果为true，则禁止使用AUTH PLAIN命令。默认为false。
mail.smtp.auth.digest-md5.disable	boolean	如果为true，则禁止使用AUTH DIGEST-MD5命令。默认为false。
mail.smtp.auth.ntlm.disable	boolean	如果为true，则禁止使用AUTH NTLM命令。默认为false。
mail.smtp.auth.ntlm.domain	String	NTLM身份验证域。
mail.smtp.auth.ntlm.flags	int	NTLM协议特定的标志。有关详细信息，请参见http://curl.haxx.se/rfc/ntlm.html#theNtlmFlags。
mail.smtp.auth.xoauth2.disable	boolean	如果为true，则禁止使用AUTHENTICATE XOAUTH2命令。 由于OAuth 2.0协议需要特殊的访问令牌而不是密码，因此默认情况下会禁用此机制。 通过将此属性显式设置为“ false”或将“ mail.smtp.auth.mechanisms”属性设置为“ XOAUTH2”，可以启用它。
mail.smtp.submitter	String	在MAIL FROM命令的AUTH标记中使用的提交者。 通常由邮件中继用于传递有关邮件原始提交者的信息。 另请参见SMTPMessage的setSubmitter方法。 邮件客户端通常不使用此功能。
mail.smtp.dsn.notify	String	RCPT命令的NOTIFY选项。要么 NEVER，或SUCCESS, FAILURE, 和 DELAY 的某种组合（以逗号分隔）。
mail.smtp.dsn.ret	String	MAIL命令的RET选项。要么 FULL 或 HDRS。
mail.smtp.allow8bitmime	boolean	如果设置为true，并且服务器支持8BITMIME扩展，则使用“quoted-printable”或“base64”编码的邮件文本部分如果遵循RFC2045规则的8bit文本，则转换为使用“8bit”编码。
mail.smtp.sendpartial	boolean	如果设置为true，并且一条消息具有一些有效和一些无效的地址，则无论如何都要发送该消息，并通过SendFailedException报告部分失败。 如果设置为false（默认值），则在收件人地址无效的情况下，不会将邮件发送给任何收件人。
mail.smtp.sasl.enable	boolean	如果设置为true，请尝试使用javax.security.sasl包来选择用于登录的身份验证机制。默认为false。
mail.smtp.sasl.mechanisms	String	尝试使用的用空格或逗号分隔的SASL机制名称列表。
mail.smtp.sasl.authorizationid	String	在SASL身份验证中使用的授权ID。如果未设置，则使用身份验证ID（用户名）。
mail.smtp.sasl.realm	String	与DIGEST-MD5身份验证一起使用的领域。
mail.smtp.sasl.usecanonicalhostname	boolean	如果设置为true，则由InetAddress.getCanonicalHostName返回的规范主机名将传递到SASL机制，而不是用于连接的主机名。默认为false。
mail.smtp.quitwait	boolean	如果设置为false，则发送QUIT命令，并立即关闭连接。如果设置为true（默认值），则使传输等待对QUIT命令的响应。
mail.smtp.quitonsessionreject	boolean	如果设置为false（默认值），则在会话发起拒绝时不发送QUIT命令，并且连接立即关闭。如果设置为true，则使传输在关闭连接之前发送QUIT命令。
mail.smtp.reportsuccess	boolean	如果设置为true，则使传输为每个成功的地址包括一个SMTPAddressSucceededException。 还要注意，这将导致从SMTPTransport的sendMessage方法抛出SendFailedException，即使所有地址正确并且消息已成功发送也是如此。
mail.smtp.socketFactory	SocketFactory	如果设置为实现javax.net.SocketFactory接口的类，则该类将用于创建SMTP套接字。 请注意，这是类的实例，而不是名称，必须使用put方法（而不是setProperty方法）进行设置。
mail.smtp.socketFactory.class	String	如果设置，则指定实现javax.net.SocketFactory接口的类的名称。此类将用于创建SMTP套接字。
mail.smtp.socketFactory.fallback	boolean	如果设置为true，则无法使用指定的套接字工厂类创建套接字，这将导致使用java.net.Socket类创建套接字。默认为true。
mail.smtp.socketFactory.port	int	指定使用指定的套接字工厂时要连接的端口。如果未设置，将使用默认端口。
mail.smtp.ssl.enable	boolean	如果设置为true，则默认情况下使用SSL连接并使用SSL端口。对于“smtp”协议，默认为false；对于“smtps”协议，默认为true。
mail.smtp.ssl.checkserveridentity	boolean	如果设置为true，则检查RFC 2595指定的服务器身份。这些基于服务器证书内容的附加检查旨在防止中间人(man-in-the-middle)攻击。默认为false。
mail.smtp.ssl.trust	String	如果设置，并且未指定套接字工厂，则启用MailSSLSocketFactory的使用。 如果设置为“ *”，则所有主机都是受信任的。 如果设置为以空格分隔的主机列表，则这些主机是可信任的。 否则，信任取决于服务器提供的证书。
mail.smtp.ssl.socketFactory	SSLSocketFactory	如果设置为扩展javax.net.ssl.SSLSocketFactory类的类，则该类将用于创建SMTP SSL套接字。 请注意，这是类的实例，而不是名称，必须使用put方法（而不是setProperty方法）进行设置。
mail.smtp.ssl.socketFactory.class	String	如果设置，则指定扩展javax.net.ssl.SSLSocketFactory类的类的名称。此类将用于创建SMTP SSL套接字。
mail.smtp.ssl.socketFactory.port	int	指定使用指定的套接字工厂时要连接的端口。如果未设置，将使用默认端口。
mail.smtp.ssl.protocols	string	指定将为SSL连接启用的SSL协议。该属性值是javax.net.ssl.SSLSocket.setEnabledProtocols方法可接受的标记的空格分隔列表。
mail.smtp.ssl.ciphersuites	string	指定将为SSL连接启用的SSL密码套件。该属性值是javax.net.ssl.SSLSocket.setEnabledCipherSuites方法可接受的标记的空格分隔列表。
mail.smtp.starttls.enable	boolean	如果为true，则在发出任何登录命令之前，允许使用STARTTLS命令（如果服务器支持）将连接切换到 TLS-protected 的连接。 如果服务器不支持STARTTLS，则在不使用TLS的情况下继续连接。 如果不支持STARTTLS，请参阅mail.smtp.starttls.required属性失败。 请注意，必须配置适当的信任库，以便客户端信任服务器的证书。 默认为false。
mail.smtp.starttls.required	boolean	如果为true，则要求使用STARTTLS命令。如果服务器不支持STARTTLS命令，或者该命令失败，则connect方法将失败。默认为false。
mail.smtp.proxy.host	string	指定将用于连接到邮件服务器的HTTP Web代理服务器的主机名。
mail.smtp.proxy.port	string	指定HTTP Web代理服务器的端口号。默认为端口80。
mail.smtp.proxy.user	string	指定用于与HTTP Web代理服务器进行身份验证的用户名。默认情况下，不进行身份验证。
mail.smtp.proxy.password	string	指定用于与HTTP Web代理服务器进行身份验证的密码。默认情况下，不进行身份验证。
mail.smtp.socks.host	string	指定将用于连接到邮件服务器的SOCKS5代理服务器的主机名。
mail.smtp.socks.port	string	指定SOCKS5代理服务器的端口号。仅当代理服务器未使用标准端口号1080时，才应使用此选项。
mail.smtp.mailextension	String	扩展字符串追加到MAIL命令。 扩展字符串可用于指定标准SMTP服务扩展以及特定于供应商的扩展。 通常，应用程序应使用SMTPTransport方法supportsExtension来验证服务器是否支持所需的服务扩展。 请参阅RFC 1869和其他定义特定扩展名的RFC。
mail.smtp.userset	boolean	如果设置为true，则在isConnected方法中使用RSET命令而不是NOOP命令。在某些情况下，在执行许多NOOP命令后，sendmail的响应速度会很慢。使用RSET可以避免此sendmail问题。默认为false。
mail.smtp.noop.strict	boolean	如果设置为true（默认值），则坚持使用NOOP命令的250响应代码来指示成功。 isConnected方法使用NOOP命令来确定连接是否仍然有效。 一些较旧的服务器在成功时返回错误的响应代码，一些服务器根本不执行NOOP命令，因此总是返回失败代码。 将此属性设置为false可处理以这种方式损坏的服务器。 通常，当服务器超时连接时，它将发送421响应代码，客户端将其视为对它发出的下一个命令的响应。 超时连接时，某些服务器会发送错误的故障响应代码。 处理以这种方式损坏的服务器时，请勿将此属性设置为false。

通常，应用程序不需要直接使用此包中的类。 相反，他们应该使用javax.mail包（和子包）定义的API。 应用程序永远不要直接构造SMTPTransport的实例。 相反，他们应该使用Session方法getTransport来获取适当的Transport对象。

除了按Session配置控制打印调试输出外，com.sun.mail.smtp提供程序还使用Logger记录相同的信息，如下表所述：

SMTP Loggers

Logger Name	Logging Level	Purpose
com.sun.mail.smtp	CONFIG	SMTPTransport的配置
com.sun.mail.smtp	FINE	常规调试输出
com.sun.mail.smtp.protocol	FINEST	完整的协议跟踪

警告：此软件包独有的API应该被视为实验性的。将来可能会以与使用当前API的应用程序不兼容的方式对其进行更改。

---

翻译完成(2020/08/19)