jakarta.mail.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
*/
/**
* The Jakarta Mail API
* provides classes that model a mail system.
* The jakarta.mail package defines classes that are common to
* all mail systems.
* The jakarta.mail.internet package defines classes that are specific
* to mail systems based on internet standards such as MIME, SMTP, POP3, and IMAP.
* The Jakarta Mail API includes the jakarta.mail package and subpackages.
*
*
* For an overview of the Jakarta Mail API, read the
*
* Jakarta Mail specification.
*
*
* The code to send a plain text message can be as simple as the following:
*
*
* Properties props = new Properties();
* props.put("mail.smtp.host", "my-mail-server");
* Session session = Session.getInstance(props, null);
*
* try {
* MimeMessage msg = new MimeMessage(session);
* msg.setFrom("[email protected]");
* msg.setRecipients(Message.RecipientType.TO,
* "[email protected]");
* msg.setSubject("Jakarta Mail hello world example");
* msg.setSentDate(new Date());
* msg.setText("Hello, world!\n");
* Transport.send(msg, "[email protected]", "my-password");
* } catch (MessagingException mex) {
* System.out.println("send failed, exception: " + mex);
* }
*
*
* The Jakarta Mail download bundle contains many more complete examples
* in the "demo" directory.
*
*
* Don't forget to see the
*
* Jakarta Mail API FAQ
* for answers to the most common questions.
* The
* Jakarta Mail web site
* contains many additional resources.
*
* Properties
*
* The Jakarta Mail API supports the following standard properties,
* which may be set in the Session object, or in the
* Properties object used to create the Session object.
* The properties are always set as strings; the Type column describes
* how the string is interpreted. For example, use
*
*
* props.put("mail.debug", "true");
*
*
* to set the mail.debug property, which is of type boolean.
*
*
* Jakarta Mail properties
*
* Name
* Type
* Description
*
*
*
* mail.debug
* boolean
*
* The initial debug mode.
* Default is false.
*
*
*
*
* mail.from
* String
*
* The return email address of the current user, used by the
* InternetAddress method getLocalAddress.
*
*
*
*
* mail.mime.address.strict
* boolean
*
* The MimeMessage class uses the InternetAddress method
* parseHeader to parse headers in messages. This property
* controls the strict flag passed to the parseHeader
* method. The default is true.
*
*
*
*
* mail.host
* String
*
* The default host name of the mail server for both Stores and Transports.
* Used if the mail.protocol.host property isn't set.
*
*
*
*
* mail.store.protocol
* String
*
* Specifies the default message access protocol. The
* Session method getStore() returns a Store
* object that implements this protocol. By default the first Store
* provider in the configuration files is returned.
*
*
*
*
* mail.transport.protocol
* String
*
* Specifies the default message transport protocol. The
* Session method getTransport() returns a Transport
* object that implements this protocol. By default the first Transport
* provider in the configuration files is returned.
*
*
*
*
* mail.user
* String
*
* The default user name to use when connecting to the mail server.
* Used if the mail.protocol.user property isn't set.
*
*
*
*
* mail.protocol.class
* String
*
* Specifies the fully qualified class name of the provider for the
* specified protocol. Used in cases where more than one provider
* for a given protocol exists; this property can be used to specify
* which provider to use by default. The provider must still be listed
* in a configuration file.
*
*
*
*
* mail.protocol.host
* String
*
* The host name of the mail server for the specified protocol.
* Overrides the mail.host property.
*
*
*
*
* mail.protocol.port
* int
*
* The port number of the mail server for the specified protocol.
* If not specified the protocol's default port number is used.
*
*
*
*
* mail.protocol.user
* String
*
* The user name to use when connecting to mail servers
* using the specified protocol.
* Overrides the mail.user property.
*
*
*
*
*
*
* The following properties are supported by the EE4J implementation of
* Jakarta Mail, but are not currently a required part of the specification.
* The names, types, defaults, and semantics of these properties may
* change in future releases.
*
*
* Jakarta Mail implementation properties
*
* Name
* Type
* Description
*
*
*
* mail.debug.auth
* boolean
*
* Include protocol authentication commands (including usernames and passwords)
* in the debug output.
* Default is false.
*
*
*
*
* mail.debug.auth.username
* boolean
*
* Include the user name in non-protocol debug output.
* Default is true.
*
*
*
*
* mail.debug.auth.password
* boolean
*
* Include the password in non-protocol debug output.
* Default is false.
*
*
*
*
* mail.transport.protocol.address-type
* String
*
* Specifies the default message transport protocol for the specified address type.
* The Session method getTransport(Address) returns a
* Transport object that implements this protocol when the address is of the
* specified type (e.g., "rfc822" for standard internet addresses).
* By default the first Transport configured for that address type is used.
* This property can be used to override the behavior of the
* {@link jakarta.mail.Transport#send send} method of the
* {@link jakarta.mail.Transport Transport} class so that (for example) the "smtps"
* protocol is used instead of the "smtp" protocol by setting the property
* mail.transport.protocol.rfc822 to "smtps".
*
*
*
*
* mail.event.scope
* String
*
* Controls the scope of events. (See the jakarta.mail.event package.)
* By default, a separate event queue and thread is used for events for each
* Store, Transport, or Folder.
* If this property is set to "session", all such events are put in a single
* event queue processed by a single thread for the current session.
* If this property is set to "application", all such events are put in a single
* event queue processed by a single thread for the current application.
* (Applications are distinguished by their context class loader.)
*
*
*
*
* mail.event.executor
* java.util.concurrent.Executor
*
* By default, a new Thread is created for each event queue.
* This thread is used to call the listeners for these events.
* If this property is set to an instance of an Executor, the
* Executor.execute method is used to run the event dispatcher
* for an event queue. The event dispatcher runs until the
* event queue is no longer in use.
*
*
*
*
*
*
* The Jakarta Mail API also supports several System properties;
* see the {@link jakarta.mail.internet} package documentation
* for details.
*
*
* The Jakarta Mail reference
* implementation includes protocol providers in subpackages of
* org.eclipse.angus.mail. Note that the APIs to these protocol
* providers are not part of the standard Jakarta Mail API. Portable
* programs will not use these APIs.
*
*
* Nonportable programs may use the APIs of the protocol providers
* by (for example) casting a returned Folder object to a
* org.eclipse.angus.mail.imap.IMAPFolder object. Similarly for
* Store and Message objects returned from the
* standard Jakarta Mail APIs.
*
*
* The protocol providers also support properties that are specific to
* those providers. The package documentation for the
* {@code org.eclipse.angus.mail.imap IMAP}, {@code org.eclipse.angus.mail.pop3 POP3},
* and {@code org.eclipse.angus.mail.smtp SMTP} packages provide details.
*
*
* In addition to printing debugging output as controlled by the
* {@link jakarta.mail.Session Session} configuration, the current
* implementation of classes in this package log the same information using
* {@link java.util.logging.Logger} as described in the following table:
*
*
* Jakarta Mail Loggers
*
* Logger Name
* Logging Level
* Purpose
*
*
*
* jakarta.mail
* CONFIG
* Configuration of the Session
*
*
*
* jakarta.mail
* FINE
* General debugging output
*
*
*/
package jakarta.mail;