com.sun.mail.smtp.package-info Maven / Gradle / Ivy
/*
* Copyright (c) 2021 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
/**
* An SMTP protocol provider for the Jakarta Mail API
* that provides access to an SMTP server.
* Refer to RFC 821
* for more information.
*
* When sending a message, detailed information on each address that
* fails is available in an
* {@link com.sun.mail.smtp.SMTPAddressFailedException SMTPAddressFailedException}
* chained off the top level
* {@link jakarta.mail.SendFailedException SendFailedException}
* that is thrown.
* In addition, if the mail.smtp.reportsuccess property
* is set, an
* {@link com.sun.mail.smtp.SMTPAddressSucceededException
* SMTPAddressSucceededException}
* will be included in the list for each address that is successful.
* Note that this will cause a top level
* {@link jakarta.mail.SendFailedException SendFailedException}
* to be thrown even though the send was successful.
*
*
* The SMTP provider also supports ESMTP
* (RFC 1651).
* It can optionally use SMTP Authentication
* (RFC 2554)
* using the LOGIN, PLAIN, DIGEST-MD5, and NTLM mechanisms
* (RFC 4616
* and RFC 2831).
*
*
* To use SMTP authentication you'll need to set the mail.smtp.auth
* property (see below) or provide the SMTP Transport
* with a username and password when connecting to the SMTP server. You
* can do this using one of the following approaches:
*
*
* -
*
* Provide an Authenticator object when creating your mail Session
* and provide the username and password information during the
* Authenticator callback.
*
*
* Note that the mail.smtp.user property can be set to provide a
* default username for the callback, but the password will still need to be
* supplied explicitly.
*
*
* This approach allows you to use the static Transport send method
* to send messages.
*
*
* -
*
* Call the Transport connect method explicitly with username and
* password arguments.
*
*
* This approach requires you to explicitly manage a Transport object
* and use the Transport sendMessage method to send the message.
* The transport.java demo program demonstrates how to manage a Transport
* object. The following is roughly equivalent to the static
* Transport send method, but supplies the needed username and
* password:
*
*
* Transport tr = session.getTransport("smtp");
* tr.connect(smtphost, username, password);
* msg.saveChanges(); // don't forget this
* tr.sendMessage(msg, msg.getAllRecipients());
* tr.close();
*
*
*
*
* When using DIGEST-MD5 authentication,
* you'll also need to supply an appropriate realm;
* your mail server administrator can supply this information.
* You can set this using the mail.smtp.sasl.realm property,
* or the setSASLRealm method on SMTPTransport.
*
*
* The SMTP protocol provider can use SASL
* (RFC 2222)
* authentication mechanisms on systems that support the
* javax.security.sasl APIs, such as J2SE 5.0.
* In addition to the SASL mechanisms that are built into
* the SASL implementation, users can also provide additional
* SASL mechanisms of their own design to support custom authentication
* schemes. See the
*
* Java SASL API Programming and Deployment Guide for details.
* Note that the current implementation doesn't support SASL mechanisms
* that provide their own integrity or confidentiality layer.
*
*
* Support for OAuth 2.0 authentication via the
*
* XOAUTH2 authentication mechanism is provided either through the SASL
* support described above or as a built-in authentication mechanism in the
* SMTP provider.
* The OAuth 2.0 Access Token should be passed as the password for this mechanism.
* See
* OAuth2 Support for details.
*
*
* SMTP can also optionally request Delivery Status Notifications
* (RFC 1891).
* The delivery status will typically be reported using
* a "multipart/report"
* (RFC 1892)
* message type with a "message/delivery-status"
* (RFC 1894)
* part.
* You can use the classes in the com.sun.mail.dsn package to
* handle these MIME types.
* Note that you'll need to include dsn.jar in your CLASSPATH
* as this support is not included in mail.jar.
*
*
* See below for the properties to enable these features.
*
*
* Note also that THERE IS NOT SUFFICIENT DOCUMENTATION HERE TO USE THESE
* FEATURES!!! You will need to read the appropriate RFCs mentioned above
* to understand what these features do and how to use them. Don't just
* start setting properties and then complain to us when it doesn't work
* like you expect it to work. READ THE RFCs FIRST!!!
*
*
* The SMTP protocol provider supports the CHUNKING extension defined in
* RFC 3030.
* Set the mail.smtp.chunksize property to the desired chunk
* size in bytes.
* If the server supports the CHUNKING extension, the BDAT command will be
* used to send the message in chunksize pieces. Note that no pipelining is
* done so this will be slower than sending the message in one piece.
* Note also that the BINARYMIME extension described in RFC 3030 is NOT supported.
*
* Properties
*
* The SMTP protocol provider supports the following properties,
* which may be set in the Jakarta Mail Session object.
* The properties are always set as strings; the Type column describes
* how the string is interpreted. For example, use
*
*
* props.put("mail.smtp.port", "888");
*
*
* to set the mail.smtp.port property, which is of type int.
*
*
* Note that if you're using the "smtps" protocol to access SMTP over SSL,
* all the properties would be named "mail.smtps.*".
*
*
* SMTP properties
*
* Name
* Type
* Description
*
*
*
* mail.smtp.user
* String
* Default user name for SMTP.
*
*
*
* mail.smtp.host
* String
* The SMTP server to connect to.
*
*
*
* mail.smtp.port
* int
* The SMTP server port to connect to, if the connect() method doesn't
* explicitly specify one. Defaults to 25.
*
*
*
* mail.smtp.connectiontimeout
* int
* Socket connection timeout value in milliseconds.
* This timeout is implemented by java.net.Socket.
* Default is infinite timeout.
*
*
*
* mail.smtp.timeout
* int
* Socket read timeout value in milliseconds.
* This timeout is implemented by java.net.Socket.
* Default is infinite timeout.
*
*
*
* mail.smtp.writetimeout
* int
* Socket write timeout value in milliseconds.
* This timeout is implemented by using a
* java.util.concurrent.ScheduledExecutorService per connection
* that schedules a thread to close the socket if the timeout expires.
* Thus, the overhead of using this timeout is one thread per connection.
* Default is infinite timeout.
*
*
*
* mail.smtp.from
* String
*
* Email address to use for SMTP MAIL command. This sets the envelope
* return address. Defaults to msg.getFrom() or
* InternetAddress.getLocalAddress(). NOTE: mail.smtp.user was previously
* used for this.
*
*
*
*
* mail.smtp.localhost
* String
*
* Local host name used in the SMTP HELO or EHLO command.
* Defaults to InetAddress.getLocalHost().getHostName().
* Should not normally need to
* be set if your JDK and your name service are configured properly.
*
*
*
*
* mail.smtp.localaddress
* String
*
* Local address (host name) to bind to when creating the SMTP socket.
* Defaults to the address picked by the Socket class.
* Should not normally need to be set, but useful with multi-homed hosts
* where it's important to pick a particular local address to bind to.
*
*
*
*
* mail.smtp.localport
* int
*
* Local port number to bind to when creating the SMTP socket.
* Defaults to the port number picked by the Socket class.
*
*
*
*
* mail.smtp.ehlo
* boolean
*
* If false, do not attempt to sign on with the EHLO command. Defaults to
* true. Normally failure of the EHLO command will fallback to the HELO
* command; this property exists only for servers that don't fail EHLO
* properly or don't implement EHLO properly.
*
*
*
*
* mail.smtp.auth
* boolean
* If true, attempt to authenticate the user using the AUTH command.
* Defaults to false.
*
*
*
* mail.smtp.auth.mechanisms
* String
*
* If set, lists the authentication mechanisms to consider, and the order
* in which to consider them. Only mechanisms supported by the server and
* supported by the current implementation will be used.
* The default is "LOGIN PLAIN DIGEST-MD5 NTLM", which includes all
* the authentication mechanisms supported by the current implementation
* except XOAUTH2.
*
*
*
*
* mail.smtp.auth.login.disable
* boolean
* If true, prevents use of the AUTH LOGIN command.
* Default is false.
*
*
*
* mail.smtp.auth.plain.disable
* boolean
* If true, prevents use of the AUTH PLAIN command.
* Default is false.
*
*
*
* mail.smtp.auth.digest-md5.disable
* boolean
* If true, prevents use of the AUTH DIGEST-MD5 command.
* Default is false.
*
*
*
* mail.smtp.auth.ntlm.disable
* boolean
* If true, prevents use of the AUTH NTLM command.
* Default is false.
*
*
*
* mail.smtp.auth.ntlm.domain
* String
*
* The NTLM authentication domain.
*
*
*
*
* mail.smtp.auth.ntlm.flags
* int
*
* NTLM protocol-specific flags.
* See
* http://curl.haxx.se/rfc/ntlm.html#theNtlmFlags for details.
*
*
*
*
*
*
* mail.smtp.auth.xoauth2.disable
* boolean
* If true, prevents use of the AUTHENTICATE XOAUTH2 command.
* Because the OAuth 2.0 protocol requires a special access token instead of
* a password, this mechanism is disabled by default. Enable it by explicitly
* setting this property to "false" or by setting the "mail.smtp.auth.mechanisms"
* property to "XOAUTH2".
*
*
*
* mail.smtp.submitter
* String
* The submitter to use in the AUTH tag in the MAIL FROM command.
* Typically used by a mail relay to pass along information about the
* original submitter of the message.
* See also the {@link com.sun.mail.smtp.SMTPMessage#setSubmitter setSubmitter}
* method of {@link com.sun.mail.smtp.SMTPMessage SMTPMessage}.
* Mail clients typically do not use this.
*
*
*
*
* mail.smtp.dsn.notify
* String
* The NOTIFY option to the RCPT command. Either NEVER, or some
* combination of SUCCESS, FAILURE, and DELAY (separated by commas).
*
*
*
* mail.smtp.dsn.ret
* String
* The RET option to the MAIL command. Either FULL or HDRS.
*
*
*
* mail.smtp.allow8bitmime
* boolean
*
* If set to true, and the server supports the 8BITMIME extension, text
* parts of messages that use the "quoted-printable" or "base64" encodings
* are converted to use "8bit" encoding if they follow the RFC2045 rules
* for 8bit text.
*
*
*
*
* mail.smtp.sendpartial
* boolean
*
* If set to true, and a message has some valid and some invalid
* addresses, send the message anyway, reporting the partial failure with
* a SendFailedException. If set to false (the default), the message is
* not sent to any of the recipients if there is an invalid recipient
* address.
*
*
*
*
* mail.smtp.sasl.enable
* boolean
*
* If set to true, attempt to use the javax.security.sasl package to
* choose an authentication mechanism for login.
* Defaults to false.
*
*
*
*
* mail.smtp.sasl.mechanisms
* String
*
* A space or comma separated list of SASL mechanism names to try
* to use.
*
*
*
*
* mail.smtp.sasl.authorizationid
* String
*
* The authorization ID to use in the SASL authentication.
* If not set, the authentication ID (user name) is used.
*
*
*
*
* mail.smtp.sasl.realm
* String
* The realm to use with DIGEST-MD5 authentication.
*
*
*
* mail.smtp.sasl.usecanonicalhostname
* boolean
*
* If set to true, the canonical host name returned by
* {@link java.net.InetAddress#getCanonicalHostName InetAddress.getCanonicalHostName}
* is passed to the SASL mechanism, instead of the host name used to connect.
* Defaults to false.
*
*
*
*
* mail.smtp.quitwait
* boolean
*
* If set to false, the QUIT command is sent
* and the connection is immediately closed.
* If set to true (the default), causes the transport to wait
* for the response to the QUIT command.
*
*
*
*
* mail.smtp.quitonsessionreject
* boolean
*
* If set to false (the default), on session initiation rejection the QUIT
* command is not sent and the connection is immediately closed.
* If set to true, causes the transport to send the QUIT command prior to
* closing the connection.
*
*
*
*
* mail.smtp.reportsuccess
* boolean
*
* If set to true, causes the transport to include an
* {@link com.sun.mail.smtp.SMTPAddressSucceededException
* SMTPAddressSucceededException}
* for each address that is successful.
* Note also that this will cause a
* {@link jakarta.mail.SendFailedException SendFailedException}
* to be thrown from the
* {@link com.sun.mail.smtp.SMTPTransport#sendMessage sendMessage}
* method of
* {@link com.sun.mail.smtp.SMTPTransport SMTPTransport}
* even if all addresses were correct and the message was sent
* successfully.
*
*
*
*
* mail.smtp.socketFactory
* SocketFactory
*
* If set to a class that implements the
* javax.net.SocketFactory interface, this class
* will be used to create SMTP sockets. Note that this is an
* instance of a class, not a name, and must be set using the
* put method, not the setProperty method.
*
*
*
*
* mail.smtp.socketFactory.class
* String
*
* If set, specifies the name of a class that implements the
* javax.net.SocketFactory interface. This class
* will be used to create SMTP sockets.
*
*
*
*
* mail.smtp.socketFactory.fallback
* boolean
*
* If set to true, failure to create a socket using the specified
* socket factory class will cause the socket to be created using
* the java.net.Socket class.
* Defaults to true.
*
*
*
*
* mail.smtp.socketFactory.port
* int
*
* Specifies the port to connect to when using the specified socket
* factory.
* If not set, the default port will be used.
*
*
*
*
* mail.smtp.ssl.enable
* boolean
*
* If set to true, use SSL to connect and use the SSL port by default.
* Defaults to false for the "smtp" protocol and true for the "smtps" protocol.
*
*
*
*
* mail.smtp.ssl.checkserveridentity
* boolean
*
* If set to true, check the server identity as specified by
* RFC 2595.
* These additional checks based on the content of the server's certificate
* are intended to prevent man-in-the-middle attacks.
* Defaults to false.
*
*
*
*
* mail.smtp.ssl.trust
* String
*
* If set, and a socket factory hasn't been specified, enables use of a
* {@link com.sun.mail.util.MailSSLSocketFactory MailSSLSocketFactory}.
* If set to "*", all hosts are trusted.
* If set to a whitespace separated list of hosts, those hosts are trusted.
* Otherwise, trust depends on the certificate the server presents.
*
*
*
*
* mail.smtp.ssl.socketFactory
* SSLSocketFactory
*
* If set to a class that extends the
* javax.net.ssl.SSLSocketFactory class, this class
* will be used to create SMTP SSL sockets. Note that this is an
* instance of a class, not a name, and must be set using the
* put method, not the setProperty method.
*
*
*
*
* mail.smtp.ssl.socketFactory.class
* String
*
* If set, specifies the name of a class that extends the
* javax.net.ssl.SSLSocketFactory class. This class
* will be used to create SMTP SSL sockets.
*
*
*
*
* mail.smtp.ssl.socketFactory.port
* int
*
* Specifies the port to connect to when using the specified socket
* factory.
* If not set, the default port will be used.
*
*
*
*
* mail.smtp.ssl.protocols
* string
*
* Specifies the SSL protocols that will be enabled for SSL connections.
* The property value is a whitespace separated list of tokens acceptable
* to the javax.net.ssl.SSLSocket.setEnabledProtocols method.
*
*
*
*
* mail.smtp.ssl.ciphersuites
* string
*
* Specifies the SSL cipher suites that will be enabled for SSL connections.
* The property value is a whitespace separated list of tokens acceptable
* to the javax.net.ssl.SSLSocket.setEnabledCipherSuites method.
*
*
*
*
* mail.smtp.starttls.enable
* boolean
*
* If true, enables the use of the STARTTLS command (if
* supported by the server) to switch the connection to a TLS-protected
* connection before issuing any login commands.
* If the server does not support STARTTLS, the connection continues without
* the use of TLS; see the
* mail.smtp.starttls.required
* property to fail if STARTTLS isn't supported.
* Note that an appropriate trust store must configured so that the client
* will trust the server's certificate.
* Defaults to false.
*
*
*
*
* mail.smtp.starttls.required
* boolean
*
* If true, requires the use of the STARTTLS command.
* If the server doesn't support the STARTTLS command, or the command
* fails, the connect method will fail.
* Defaults to false.
*
*
*
*
* mail.smtp.proxy.host
* string
*
* Specifies the host name of an HTTP web proxy server that will be used for
* connections to the mail server.
*
*
*
*
* mail.smtp.proxy.port
* string
*
* Specifies the port number for the HTTP web proxy server.
* Defaults to port 80.
*
*
*
*
* mail.smtp.proxy.user
* string
*
* Specifies the user name to use to authenticate with the HTTP web proxy server.
* By default, no authentication is done.
*
*
*
*
* mail.smtp.proxy.password
* string
*
* Specifies the password to use to authenticate with the HTTP web proxy server.
* By default, no authentication is done.
*
*
*
*
* mail.smtp.socks.host
* string
*
* Specifies the host name of a SOCKS5 proxy server that will be used for
* connections to the mail server.
*
*
*
*
* mail.smtp.socks.port
* string
*
* Specifies the port number for the SOCKS5 proxy server.
* This should only need to be used if the proxy server is not using
* the standard port number of 1080.
*
*
*
*
* mail.smtp.mailextension
* String
*
* Extension string to append to the MAIL command.
* The extension string can be used to specify standard SMTP
* service extensions as well as vendor-specific extensions.
* Typically the application should use the
* {@link com.sun.mail.smtp.SMTPTransport SMTPTransport}
* method {@link com.sun.mail.smtp.SMTPTransport#supportsExtension
* supportsExtension}
* to verify that the server supports the desired service extension.
* See RFC 1869
* and other RFCs that define specific extensions.
*
*
*
*
* mail.smtp.userset
* boolean
*
* If set to true, use the RSET command instead of the NOOP command
* in the {@link jakarta.mail.Transport#isConnected isConnected} method.
* In some cases sendmail will respond slowly after many NOOP commands;
* use of RSET avoids this sendmail issue.
* Defaults to false.
*
*
*
*
* mail.smtp.noop.strict
* boolean
*
* If set to true (the default), insist on a 250 response code from the NOOP
* command to indicate success. The NOOP command is used by the
* {@link jakarta.mail.Transport#isConnected isConnected} method to determine
* if the connection is still alive.
* Some older servers return the wrong response code on success, some
* servers don't implement the NOOP command at all and so always return
* a failure code. Set this property to false to handle servers
* that are broken in this way.
* Normally, when a server times out a connection, it will send a 421
* response code, which the client will see as the response to the next
* command it issues.
* Some servers send the wrong failure response code when timing out a
* connection.
* Do not set this property to false when dealing with servers that are
* broken in this way.
*
*
*
*
*
* In general, applications should not need to use the classes in this
* package directly. Instead, they should use the APIs defined by
* jakarta.mail package (and subpackages). Applications should
* never construct instances of SMTPTransport directly.
* Instead, they should use the
* Session method getTransport to acquire an
* appropriate Transport object.
*
*
* In addition to printing debugging output as controlled by the
* {@link jakarta.mail.Session Session} configuration,
* the com.sun.mail.smtp provider logs the same information using
* {@link java.util.logging.Logger} as described in the following table:
*
*
* SMTP Loggers
*
* Logger Name
* Logging Level
* Purpose
*
*
*
* com.sun.mail.smtp
* CONFIG
* Configuration of the SMTPTransport
*
*
*
* com.sun.mail.smtp
* FINE
* General debugging output
*
*
*
* com.sun.mail.smtp.protocol
* FINEST
* Complete protocol trace
*
*
*
* WARNING: The APIs unique to this package should be
* considered EXPERIMENTAL. They may be changed in the
* future in ways that are incompatible with applications using the
* current APIs.
*/
package com.sun.mail.smtp;