0N/A<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0N/A<HTML>
0N/A<HEAD>
0N/A<!--
0N/A
292N/A DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
292N/A
720N/A Copyright (c) 1997-2015 Oracle and/or its affiliates. All rights reserved.
292N/A
292N/A The contents of this file are subject to the terms of either the GNU
292N/A General Public License Version 2 only ("GPL") or the Common Development
292N/A and Distribution License("CDDL") (collectively, the "License"). You
292N/A may not use this file except in compliance with the License. You can
292N/A obtain a copy of the License at
292N/A https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
292N/A or packager/legal/LICENSE.txt. See the License for the specific
292N/A language governing permissions and limitations under the License.
292N/A
292N/A When distributing the software, include this License Header Notice in each
292N/A file and include the License file at packager/legal/LICENSE.txt.
0N/A
292N/A GPL Classpath Exception:
292N/A Oracle designates this particular file as subject to the "Classpath"
292N/A exception as provided by Oracle in the GPL Version 2 section of the License
292N/A file that accompanied this code.
292N/A
292N/A Modifications:
292N/A If applicable, add the following below the License Header, with the fields
292N/A enclosed by brackets [] replaced by your own identifying information:
292N/A "Portions Copyright [year] [name of copyright owner]"
292N/A
292N/A Contributor(s):
292N/A If you wish your version of this file to be governed by only the CDDL or
292N/A only the GPL Version 2, indicate your decision by adding "[Contributor]
292N/A elects to include this software in this distribution under the [CDDL or GPL
292N/A Version 2] license." If you don't indicate a single choice of license, a
292N/A recipient has the option to distribute your version of this file under
292N/A either the CDDL, the GPL Version 2 or to extend the choice of license to
292N/A its licensees as provided above. However, if you add GPL Version 2 code
292N/A and therefore, elected the GPL Version 2 license, then the option applies
292N/A only if the new code is made subject to such option by the copyright
292N/A holder.
0N/A
0N/A-->
0N/A
0N/A</HEAD>
0N/A<BODY BGCOLOR="white">
0N/A
0N/AThe JavaMail<sup><font size="-2">TM</font></sup> API
0N/Aprovides classes that model a mail system.
0N/AThe <code>javax.mail</code> package defines classes that are common to
0N/Aall mail systems.
0N/AThe <code>javax.mail.internet</code> package defines classes that are specific
0N/Ato mail systems based on internet standards such as MIME, SMTP, POP3, and IMAP.
0N/AThe JavaMail API includes the <code>javax.mail</code> package and subpackages.
0N/A<P>
720N/AFor an overview of the JavaMail API, read the
720N/A<A HREF="http://javamail.java.net/nonav/docs/JavaMail-1.5.pdf" TARGET="_top">
720N/AJavaMail specification</A>.
0N/A<P>
0N/AThe code to send a plain text message can be as simple as the following:
0N/A<PRE>
0N/A Properties props = new Properties();
0N/A props.put("mail.smtp.host", "my-mail-server");
0N/A Session session = Session.getInstance(props, null);
0N/A
0N/A try {
0N/A MimeMessage msg = new MimeMessage(session);
520N/A msg.setFrom("me@example.com");
0N/A msg.setRecipients(Message.RecipientType.TO,
0N/A "you@example.com");
0N/A msg.setSubject("JavaMail hello world example");
0N/A msg.setSentDate(new Date());
0N/A msg.setText("Hello, world!\n");
520N/A Transport.send(msg, "me@example.com", "my-password");
0N/A } catch (MessagingException mex) {
0N/A System.out.println("send failed, exception: " + mex);
0N/A }
0N/A</PRE>
0N/AThe JavaMail download bundle contains many more complete examples
0N/Ain the "demo" directory.
0N/A<P>
0N/ADon't forget to see the
324N/A<A HREF="http://www.oracle.com/technetwork/java/javamail/faq/" TARGET="_top">
0N/AJavaMail API FAQ</A>
0N/Afor answers to the most common questions.
324N/AThe <A HREF="http://www.oracle.com/technetwork/java/javamail/" TARGET="_top">
0N/AJavaMail web site</A>
0N/Acontains many additional resources.
0N/A<P>
809N/A<A NAME="properties">
809N/A<H4>Properties</H4>
809N/A</A>
0N/AThe JavaMail API supports the following standard properties,
0N/Awhich may be set in the <code>Session</code> object, or in the
0N/A<code>Properties</code> object used to create the <code>Session</code> object.
0N/AThe properties are always set as strings; the Type column describes
0N/Ahow the string is interpreted. For example, use
0N/A<PRE>
0N/A props.put("mail.debug", "true");
0N/A</PRE>
0N/Ato set the <code>mail.debug</code> property, which is of type boolean.
0N/A<P>
0N/A<TABLE BORDER>
0N/A<TR>
0N/A<TH>Name</TH>
0N/A<TH>Type</TH>
0N/A<TH>Description</TH>
0N/A</TR>
0N/A
809N/A<A NAME="mail.debug"></A>
809N/A<TR id="mail.debug">
0N/A<TD>mail.debug</TD>
0N/A<TD>boolean</TD>
0N/A<TD>
0N/AThe initial debug mode.
0N/ADefault is false.
0N/A</TD>
0N/A</TR>
0N/A
809N/A<A NAME="mail.from"></A>
809N/A<TR id="mail.from">
0N/A<TD>mail.from</TD>
0N/A<TD>String</TD>
0N/A<TD>
0N/AThe return email address of the current user, used by the
0N/A<code>InternetAddress</code> method <code>getLocalAddress</code>.
0N/A</TD>
0N/A</TR>
0N/A
809N/A<A NAME="mail.mime.address.strict"></A>
809N/A<TR id="mail.mime.address.strict">
0N/A<TD>mail.mime.address.strict</TD>
0N/A<TD>boolean</TD>
0N/A<TD>
0N/AThe MimeMessage class uses the <code>InternetAddress</code> method
0N/A<code>parseHeader</code> to parse headers in messages. This property
0N/Acontrols the strict flag passed to the <code>parseHeader</code>
0N/Amethod. The default is true.
0N/A</TD>
0N/A</TR>
0N/A
809N/A<A NAME="mail.host"></A>
809N/A<TR id="mail.host">
0N/A<TD>mail.host</TD>
0N/A<TD>String</TD>
0N/A<TD>
0N/AThe default host name of the mail server for both Stores and Transports.
0N/AUsed if the <code>mail.<i>protocol</i>.host</code> property isn't set.
0N/A</TD>
0N/A</TR>
0N/A
809N/A<A NAME="mail.store.protocol"></A>
809N/A<TR id="mail.store.protocol">
0N/A<TD>mail.store.protocol</TD>
0N/A<TD>String</TD>
0N/A<TD>
0N/ASpecifies the default message access protocol. The
0N/A<code>Session</code> method <code>getStore()</code> returns a Store
0N/Aobject that implements this protocol. By default the first Store
0N/Aprovider in the configuration files is returned.
0N/A</TD>
0N/A</TR>
0N/A
809N/A<A NAME="mail.transport.protocol"></A>
809N/A<TR id="mail.transport.protocol">
0N/A<TD>mail.transport.protocol</TD>
0N/A<TD>String</TD>
0N/A<TD>
137N/ASpecifies the default message transport protocol. The
0N/A<code>Session</code> method <code>getTransport()</code> returns a Transport
0N/Aobject that implements this protocol. By default the first Transport
0N/Aprovider in the configuration files is returned.
0N/A</TD>
0N/A</TR>
0N/A
809N/A<A NAME="mail.user"></A>
809N/A<TR id="mail.user">
0N/A<TD>mail.user</TD>
0N/A<TD>String</TD>
0N/A<TD>
0N/AThe default user name to use when connecting to the mail server.
0N/AUsed if the <code>mail.<i>protocol</i>.user</code> property isn't set.
0N/A</TD>
0N/A</TR>
0N/A
809N/A<A NAME="mail.protocol.class"></A>
809N/A<TR id="mail.protocol.class">
0N/A<TD>mail.<i>protocol</i>.class</TD>
0N/A<TD>String</TD>
0N/A<TD>
0N/ASpecifies the fully qualified class name of the provider for the
0N/Aspecified protocol. Used in cases where more than one provider
0N/Afor a given protocol exists; this property can be used to specify
0N/Awhich provider to use by default. The provider must still be listed
0N/Ain a configuration file.
0N/A</TD>
0N/A</TR>
0N/A
809N/A<A NAME="mail.protocol.host"></A>
809N/A<TR id="mail.protocol.host">
0N/A<TD>mail.<i>protocol</i>.host</TD>
0N/A<TD>String</TD>
0N/A<TD>
0N/AThe host name of the mail server for the specified protocol.
0N/AOverrides the <code>mail.host</code> property.
0N/A</TD>
0N/A</TR>
0N/A
809N/A<A NAME="mail.protocol.port"></A>
809N/A<TR id="mail.protocol.port">
0N/A<TD>mail.<i>protocol</i>.port</TD>
0N/A<TD>int</TD>
0N/A<TD>
0N/AThe port number of the mail server for the specified protocol.
0N/AIf not specified the protocol's default port number is used.
0N/A</TD>
0N/A</TR>
0N/A
809N/A<A NAME="mail.protocol.user"></A>
809N/A<TR id="mail.protocol.user">
0N/A<TD>mail.<i>protocol</i>.user</TD>
0N/A<TD>String</TD>
0N/A<TD>
0N/AThe user name to use when connecting to mail servers
0N/Ausing the specified protocol.
0N/AOverrides the <code>mail.user</code> property.
0N/A</TD>
0N/A</TR>
0N/A
0N/A</TABLE>
137N/A
137N/A<P>
575N/AThe following properties are supported by the reference implementation (RI) of
137N/AJavaMail, but are not currently a required part of the specification.
137N/AThe names, types, defaults, and semantics of these properties may
137N/Achange in future releases.
137N/A<P>
137N/A<TABLE BORDER>
137N/A<TR>
137N/A<TH>Name</TH>
137N/A<TH>Type</TH>
137N/A<TH>Description</TH>
137N/A</TR>
137N/A
809N/A<A NAME="mail.debug.auth"></A>
809N/A<TR id="mail.debug.auth">
433N/A<TD>mail.debug.auth</TD>
433N/A<TD>boolean</TD>
433N/A<TD>
433N/AInclude protocol authentication commands (including usernames and passwords)
433N/Ain the debug output.
433N/ADefault is false.
433N/A</TD>
433N/A</TR>
433N/A
809N/A<A NAME="mail.transport.protocol.address-type"></A>
809N/A<TR id="mail.transport.protocol.address-type">
137N/A<TD>mail.transport.protocol.<i>address-type</i></TD>
137N/A<TD>String</TD>
137N/A<TD>
137N/ASpecifies the default message transport protocol for the specified address type.
137N/AThe <code>Session</code> method <code>getTransport(Address)</code> returns a
137N/ATransport object that implements this protocol when the address is of the
137N/Aspecified type (e.g., "rfc822" for standard internet addresses).
137N/ABy default the first Transport configured for that address type is used.
137N/AThis property can be used to override the behavior of the
137N/A{@link javax.mail.Transport#send send} method of the
137N/A{@link javax.mail.Transport Transport} class so that (for example) the "smtps"
137N/Aprotocol is used instead of the "smtp" protocol by setting the property
137N/A<code>mail.transport.protocol.rfc822</code> to <code>"smtps"</code>.
137N/A</TD>
137N/A</TR>
137N/A
809N/A<A NAME="mail.event.scope"></A>
809N/A<TR id="mail.event.scope">
720N/A<TD>mail.event.scope</TD>
720N/A<TD>String</TD>
720N/A<TD>
720N/AControls the scope of events. (See the javax.mail.event package.)
720N/ABy default, a separate event queue and thread is used for events for each
720N/AStore, Transport, or Folder.
720N/AIf this property is set to "session", all such events are put in a single
720N/Aevent queue processed by a single thread for the current session.
720N/AIf this property is set to "application", all such events are put in a single
720N/Aevent queue processed by a single thread for the current application.
720N/A(Applications are distinguished by their context class loader.)
720N/A</TD>
720N/A</TR>
720N/A
809N/A<A NAME="mail.event.executor"></A>
809N/A<TR id="mail.event.executor">
720N/A<TD>mail.event.executor</TD>
720N/A<TD>java.util.concurrent.Executor</TD>
720N/A<TD>
720N/ABy default, a new Thread is created for each event queue.
720N/AThis thread is used to call the listeners for these events.
720N/AIf this property is set to an instance of an Executor, the
720N/AExecutor.execute method is used to run the event dispatcher
720N/Afor an event queue. The event dispatcher runs until the
720N/Aevent queue is no longer in use.
720N/A</TD>
720N/A</TR>
720N/A
137N/A</TABLE>
137N/A
0N/A<P>
0N/AThe JavaMail API also supports several System properties;
0N/Asee the {@link javax.mail.internet} package documentation
0N/Afor details.
0N/A
0N/A<P>
0N/AThe JavaMail reference
575N/Aimplementation includes protocol providers in subpackages of
0N/A<code>com.sun.mail</code>. Note that the APIs to these protocol
0N/Aproviders are not part of the standard JavaMail API. Portable
0N/Aprograms will not use these APIs.
0N/A<P>
575N/ANonportable programs may use the APIs of the protocol providers
0N/Aby (for example) casting a returned <code>Folder</code> object to a
0N/A<code>com.sun.mail.imap.IMAPFolder</code> object. Similarly for
0N/A<code>Store</code> and <code>Message</code> objects returned from the
0N/Astandard JavaMail APIs.
0N/A<P>
575N/AThe protocol providers also support properties that are specific to
0N/Athose providers. The package documentation for the
0N/A{@link com.sun.mail.imap IMAP}, {@link com.sun.mail.pop3 POP3},
0N/Aand {@link com.sun.mail.smtp SMTP} packages provide details.
720N/A<P>
720N/AIn addition to printing debugging output as controlled by the
720N/A{@link javax.mail.Session Session} configuration, the current
720N/Aimplementation of classes in this package log the same information using
720N/A{@link java.util.logging.Logger} as described in the following table:
720N/A<P>
720N/A<TABLE BORDER>
720N/A<TR>
720N/A<TH>Logger Name</TH>
720N/A<TH>Logging Level</TH>
720N/A<TH>Purpose</TH>
720N/A</TR>
720N/A
720N/A<TR>
720N/A<TD>javax.mail</TD>
720N/A<TD>CONFIG</TD>
720N/A<TD>Configuration of the Session</TD>
720N/A</TR>
720N/A
720N/A<TR>
720N/A<TD>javax.mail</TD>
720N/A<TD>FINE</TD>
720N/A<TD>General debugging output</TD>
720N/A</TR>
720N/A</TABLE>
0N/A
0N/A</BODY>
0N/A</HTML>