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)