JAVAMAIL API FAQ

what does a prepaid envelope look like

Q: What is the JavaMail API?

A: The JavaMail API is a set of abstract APIs that model a mail system. The API provides a platform independent and protocol independent framework to build Java technology based email client applications. The JavaMail API provides facilities for reading and sending email. Service providers implement particular protocols. Several service providers are included with the JavaMail API package; others are available separately. The JavaMail API is implemented as a Java optional package that can be used on JDK 1.4 and later on any operating system. The JavaMail API is also a required part of the Java Platform, Enterprise Edition (Java EE) .

Q: How do I get an implementation of the JavaMail API?

A: Oracle provides a royalty-free reference implementation, in binary form, that developers may use and ship. The reference implementation includes the core JavaMail packages and IMAP, POP3, and SMTP service providers. The reference implementation may be downloaded here .

Q: How do I send feedback or comments?

Q: Where is javax.activation ?

A: POP3 stands for Post Office Protocol version 3. POP3 is a very limited protocol for accessing a single mailbox. It is much less capable than IMAP. POP3 is very widely used and is defined by RFC1939 .

Q: What about support for MAPI, NNTP, Lotus Notes, and other service providers?

Q: Is the JavaMail API implementation completely free? Can I ship it along with my product?

A: Yes. The JavaMail API implementation is completely free and open source and you can include it in your product. This release includes IMAP, POP3, and SMTP providers as well. Please do read the license and ensure that you understand it. The JavaMail license is described here .

Q: Can I get the source code for the JavaMail API implementation?

A: Starting with JavaMail 1.4.2, the source code for the JavaMail API Reference Implementation is available under the CDDL or GPL open source licenses in the JavaMail project at Kenai. You'll need Mercurial to check out the source code. Previous releases of JavaMail are also available as part of Project GlassFish. See the mail module page at GlassFish for more details.

Q: Is JavaMail Y2K compliant?

A: Yes. Oracle's JavaMail implementation is Option-3 Y2K compliant. Please see the NOTES.txt file in the JavaMail package for more information.

Q: The answer to my question isn't here, where else should I look?

A: In addition to the JavaMail API spec and javadocs (available from our main web page ), don't forget to check the README.txt and NOTES.txt files for additional important information.

You can reach the JavaMail team directly at javamail_ww@oracle.com. You can use this address to report bugs. Bugs can also be reported using the Issue Tracker at the JavaMail project .

The Oracle Technology Network maintains a JavaMail forum, see the JavaMail Forum .

jGuru also maintains a JavaMail FAQ, which you'll find at http://www.jguru.com/faq/JavaMail. although it hasn't been updated in several years.

Installation and Configuration

Q: How do I install the JavaMail API implementation?

A: Unzip the distribution zip file and edit your CLASSPATH environment variable to include the mail.jar file that was included with the JavaMail API distribution. You will also need an implementation of the JavaBeans Activation Framework (see below) unless you're using JDK 1.6 or newer (which includes JAF). See the README.txt file (also included in the download package) for additional details and examples, as well as the following FAQ entry .

Q: I get a ClassNotFoundException when I run my program.

A: You haven't set CLASSPATH properly. See Setting the class path (Windows) or Setting the class path (Solaris/Linux) in the JDK documentation. Note that if you're running your program using "java -jar", the CLASSPATH environment variable setting is ignored. In that case you'll need to add the "-classpath" argument to the java command, or add the Class-Path header to the manifest file of your jar file. See the Java Tutorial and this Wikipedia article for more information.

Q: How do I set my CLASSPATH on Windows?

A: Detailed instructions are available here

Q: How do I add the JavaMail library to my NetBeans Java Project?

A: Use the Library Manager to create a library and add a reference to that library to your project.

  1. Inside Netbeans, open the Library Manager (Tools > Libraries from the main menu bar).
  2. Select <New Library. >
  3. Enter a library name, e.g. "JavaMail", and hit <OK>. Do not check server library.
  4. Make sure the new library is selected under "Libraries" on the left.
  5. Select the "Classpath" tab on the right and choose <Add Jar/Folder. >
  6. Using the file browser, select mail.jar from your JavaMail installation (e.g. /javamail-1.4.3/mail.jar), and hit <Add Jar/Folder> to accept.
  7. Select the "Javadoc" tab and choose <Add ZIP/Folder. >
  8. Using the file browser, select the folder where the JavaMail javadoc index files are (e.g. /javamail-1.4.3/docs/javadocs"), and hit <Add ZIP/Folder> to accept.
  9. If you downloaded the JavaMail source code. you can set the source code reference on the "Sources" tab. This can be helpful for debugging. Using the file browser, select the source root for the JavaMail sources (". /javamail-1.4.3/mail/src/main/java" for 1.4.3) and hit <Add Jar/Folder> to accept.

Note: If you are using JDK 1.5.0 or earlier you will need to add the JavaBeans Activation Framework library as well. You can create a separate library in a manner similar to the above, or just add activation.jar (and javadoc/source references if desired) to this library definition.

Now add a reference to this library to your project.

  1. Open your project in NetBeans and make sure the "Projects" tab is visible.
  2. Right click your project in the project explorer and select "Properties"
  3. In the Properties dialog, select "Libraries" in the tree on the left and make sure the "Compile" tab is selected.
  4. Click <Add Library. >
  5. Locate and select the library you created above and click "Add Library". It should be added to the list of compile-time libraries.
  6. Click "OK" and you're done.

Q: How do I add the JavaMail library to my Eclipse Java Project?

A: Create a "user library" for JavaMail and add a reference to that library to your project.

  1. From the Eclipse main menu, open Window > Preferences
  2. Open the tree to Java > Build Path > User Libraries and select the <User Libraries> node.
  3. Choose <New. > from the panel on the right
  4. In the new library dialog, enter a user library name, e.g. "JavaMail", and hit <OK>. Do not check system library.
  5. Make sure the new library is selected and choose <Add Jars. >
  6. Browse to where JavaMail is installed and select mail.jar
  7. Select <Javadoc location: (None)> and hit <Edit. > to add a reference to the javadoc location. This can be found at docs/javadocs under the same folder where you installed JavaMail.
  8. You can also set the source code reference here if you downloaded the JavaMail source code. Use ". /javamail-1.4.2/mail/src/main/java" as the source root for 1.4.2 or ". /glassfish/mail/src/java" as the source root for 1.4.1.
  9. Choose <OK> to close the Preferences dialog. JavaMail is now installed as a Library in Eclipse.

Note: If you are using JDK 1.5.0 or earlier you will need to add the JavaBeans Activation Framework library as well. You can create a separate library in a manner similar to the above, or just add activation.jar (and javadoc/source references if desired) to this library definition.

Now use the JavaMail

library in your Eclipse Java Project (Eclipse 3.4)

  1. Open your project in Eclipse and be in the Java Perspective
  2. Right click your project in the project explorer and select "Build Path > Configure Build Path. "
  3. In the Properties dialog that opens, ensure Java Build Path is selected in the tree on the left and select the Libraries tab on the right
  4. Click <Add Library. >
  5. Select "User Library", then click <Next>
  6. Locate and select the JavaMail library added in the previous step, click "Finish", and you're done.

This article explains how to make the JavaMail source code available to your Eclipse project.

Q: Does JavaMail include all the necessary mail servers?

A: No, the JavaMail API package does not include any mail servers. To use the JavaMail API package, you'll need to have access to an IMAP or POP3 mail server (for reading mail) and/or an SMTP mail server (for sending mail). These mail servers are usually provided by your Internet Service Provider or are a part of your organization's networking infrastructure. If you don't have access to such a mail server, see below.

Q: Where can I get the necessary mail servers?

A: The University of Washington IMAP server supports multiple platforms (UNIX, Windows 32bit, etc). Get the source code from ftp://ftp.cac.washington.edu/imap/imap.tar.Z. There are several free, all Java mail servers available, including Apache James and Java Email Server. Sendmail is a popular (non-Java) SMTP server. SubEthaSMTP is a Java library for implementing SMTP server functionality; their web page also references other mail servers. Many other vendors provide mail servers supporting Internet standards. There are also many free, public mail servers that support the required mail protocols such as Gmail, Yahoo! Mail, Hotmail, etc.

Q: What host name, user name, or password should I use?

A: We do not provide a mail server for you to use. You must use your own mail server, or one provided by your Internet Service Provider or the company you work for. Your network administrator can give you the information necessary to configure JavaMail to work with your mail server.

Q: How do I configure JavaMail to work through my proxy server?

A: JavaMail does not currently support accessing mail servers through a web proxy server. One of the major reasons for using a proxy server is to allow HTTP requests from within a corporate network to pass through a corporate firewall. The firewall will typically block most access to the Internet, but will allow requests from the proxy server to pass through. In addition, a mail server inside the corporate network will perform a similar function for email, accepting messages via SMTP and forwarding them to their ultimate destination on the Internet, and accepting incoming messages and sending them to the appropriate internal mail server.

If your proxy server supports the SOCKS V4 or V5 protocol (http://www.socks.nec.com/aboutsocks.html. RFC1928 ) and allows anonymous connections, and you're using JDK 1.5 or newer and JavaMail 1.4.5 or newer, you can configure a SOCKS proxy on a per-session, per-protocol basis by setting the "mail.smtp.socks.host" property as described in the javadocs for the com.sun.mail.smtp package. Similar properties exist for the "imap" and "pop3" protocols.

If you're using older versions of the JDK or JavaMail, you can tell the Java runtime to direct all TCP socket connections to the SOCKS server. See the Networking Properties guide for the latest documentation of the socksProxyHost and socksProxyPort properties. These are system-level properties, not JavaMail session properties. They can be set from the command line when the application is invoked, for example: java -DsocksProxyHost=myproxy. This facility can be used to direct the SMTP, IMAP, and POP3 communication from JavaMail to the SOCKS proxy server. Note that setting these properties directs all TCP sockets to the SOCKS proxy, which may have negative impact on other aspects of your application.

Without such a SOCKS server, if you want to use JavaMail to access mail servers outside the firewall indirectly, you might be able to use a program such as Corkscrew or connect to tunnel TCP connections through an HTTP proxy server. JavaMail does not support direct access through an HTTP proxy web server.

Q: When connecting to my mail server over SSL I get an exception like "unable to find valid certification path to requested target".

A: Your server is probably using a test certificate or self-signed certificate instead of a certificate signed by a commercial Certificate Authority. You'll need to install the server's certificate into your trust store. The InstallCert program will help.

Alternatively, you can set the "mail.protocol .ssl.trust" property to the host name of your mail server. See the javadocs for the protocol provider packages for details.

Other common causes of this problem are:

  • There's a firewall or anti-virus program intercepting your request.
  • There's something wrong in your JDK installation preventing it from finding the certificates for the trusted certificate authorities.
  • You're running in an application server that has overridden the JDK's list of trusted certificate authorities.

Q: While trying to run my program on Linux I get a very strange error message and the program fails. What did I do wrong?

A: The error message often looks something like this:

The problem is due to a buggy version of the unzip command used to unzip the JavaMail download package on Linux. The unzip command corrupts the mail.jar file. Get a newer version of the unzip command, or use the JDK's jar command to unzip the package.

Q: How do I use JavaMail in an application run under a SecurityManager; what permissions must I grant to the application and to JavaMail?

A: When using JavaMail in an environment with a SecurityManager, JavaMail will sometimes fail to read the configuration files in the mail.jar file. The JavaBeans Activation Framework may have the same problem reading configuration files from the activation.jar file. These default configuration files are stored as "resource" files in the META-INF directory in the jar file.

There are a number of debugging techniques that can be used to determine if this is the problem. Setting the Session property "mail.debug" to true (or calling session.setDebug(true) ) will cause JavaMail to print debugging messages as it attempts to load each configuration file. A message of the form "DEBUG: can't load default providers file" indicates that this problem might exist. Similarly, setting the System property "javax.activation.debug" to "true" (e.g. by running the program using "java -Djavax.activation.debug=true. ") will cause JAF to print debugging messages as it attempts to load each resource file. Finally, the JDK can produce helpful debugging output by setting the system property "java.security.debug" to "access:failure" (e.g. by running the program using "java -Djava.security.debug=access:failure. "). The command java -Djava.security.debug=help will display other security debugging options.

In addition to the permissions necessary to read the configuration files, the application (and JavaMail) will also need permission to connect to the mail servers it uses. If the application uses System properties to configure JavaMail (e.g. by passing the Properties object returned from System.getProperties() to the Session constructor, as many of the JavaMail demo programs do), it will also need permission to use the System Properties object. Alternatively, the application can use its own Properties object and be sure to set the "mail.from" property or the "mail.user" and "mail.host" properties (see the InternetAddress.getLocalAddress() method).

To allow an application to use JavaMail under a SecurityManager, the application, JavaMail, and JAF will need permissions such as the following (be sure to replace the host and path names with appropriate values); add these to the security policy file used by the application:

Source: www.oracle.com

Category: Bank

Similar articles: