JavaMail API

Preface

Elliotte Rusty Harold

[e-mail]

Email was the Internet’s first killer app. One of the most frequently asked questions about Java is how to send email from a Java applet or application. While it’s certainly possible to write a Java program that uses sockets to communicate with mail servers, this requires detailed knowledge of some fairly complicated protocols, such as SMTP, POP, and IMAP. Just as the URL class makes interacting with HTTP servers a lot simpler than it would be with raw sockets, so too can a class library dedicated to handling email make writing email clients a lot simpler.

The JavaMail API is a standard extension to Java that provides a class library for email clients. It’s a required component of the Java Platform, Enterprise Edition. The JavaMail API can be implemented in pure Java using sockets and streams, and indeed Oracle’s reference implementation is so implemented. Programs use the JavaMail API to communicate with SMTP, POP, and IMAP servers to send and receive email. By taking advantage of this API, you can avoid focusing on the low-level protocol details and focus instead on what you want to say with the message. Custom providers can support the proprietary features of mail systems such as Gmail and Microsoft Exchange. You can even install providers that add support for NNTP, the protocol used to transport Usenet news.

There’s no limit to the uses Java programs have for the JavaMail API. Most obviously, you can write standard email clients such as Thunderbird. Or it can be used for email-intensive applications such as mailing list managers, like listproc. But the JavaMail API is also useful as a part of larger applications that simply need to send or receive a little email. For instance, a server-monitoring application can periodically load pages from a web server running on a different host and email the webmaster if the web server has crashed. An applet can use email to send data to any process or person on the Internet that has an email address, in essence using the web server’s SMTP server as a simple proxy to bypass the usual security restrictions about whom an applet is allowed to talk to. In reverse, an applet can talk to an IMAP server on the applet host to receive data from many hosts around the Net. A newsreader could be implemented as a custom service provider that treats NNTP as just one more means of exchanging messages. And that’s just the beginning of the sort of programs the JavaMail API makes it very straightforward to write.

Who You Are

This book assumes you are comfortable with the Java language and programming environment, in addition to object-oriented programming in general. This book does not attempt to be a basic language tutorial. You should be thoroughly familiar with the syntax of Java. You should have written at least simple applications.

Java Versions

This book is written with the assumption that you are coding with at least Java 5.0. In general, I use Java 5 features like generics and the enhanced for loop freely without further explanation. With respect to the JavaMail API, the distinction between Java 5 and Java 6 is not large. Most examples look identical in the two versions.

Java 7 is a bit more of a stretch. I have not shied away from using features introduced in Java 7 where they seemed especially useful or convenient—for instance, try-with-resources and multicatch are both very helpful when fitting examples into the limited space available in a printed book—but I have been careful to point out my use of such features.

As to JavaMail itself, this book covers JavaMail 1.5 which requires Java 5 or later. If for some reason you’re stuck on Java 1.4, JavaMail 1.4.1 is still available and will work with your JDK. Whichever version you use, the JavaMail API is not bundled with the base JDK or JRE, even in Java 8. You can download it separately from https://java.net/projects/javamail/.

Conventions Used in This Book

Body text is Times Roman, normal, like you’re reading now.

A monospaced typewriter font is used for:

• Code examples and fragments
• Anything that might appear in a Java program, including keywords, operators, data types, method names, variable names, class names, and interface names
• Program output
• Tags that might appear in an HTML document

A bold monospaced font is used for:

• Command lines and options that should be typed verbatim on the screen

An italicized font is used for:

• New terms where they are defined
• Pathnames, filenames, and program names (however, if the program name is also the name of a Java class, it is given in a monospaced font, like other class names)
• Host and domain names (java.oreilly.com)
• URLs (http://www.cafeaulait.org/slides/)
• Titles of other chapters and books (JavaI/O)

Significant code fragments and complete programs are generally placed into a separate paragraph, like this:

Message msg = new MimeMessage(session);
Address elliotte = new InternetAddress("[e-mail]");
msg.setFrom(elliotte);

When code is presented as fragments rather than complete programs, the existence of the appropriate import statements should be inferred. For example, in the above code fragment you may assume that javax.mail.Address and javax.mail.Message were imported.

Tip

Indicates a tip, suggestion, or general note.

Warning

Indicates a warning or caution.

Request for Comments

I enjoy hearing from readers, whether with general comments about this book, specific corrections, other topics you would like to see covered, or just war stories about your own network programming travails. You can reach me by sending email to [e-mail]. Please realize, however, that I receive several hundred pieces of email a day and cannot personally respond to each one. For the best chances of getting a personal response, please identify yourself as a reader of this book. If you have a question about a particular program that isn’t working as you expect, try to reduce it to the simplest case that reproduces the bug, preferably a single class, and paste the text of the entire program into the body of your email. Unsolicited attachments will be deleted unopened. And please, please send the message from the account you want me to reply to and make sure that your Reply-to address is properly set! There’s nothing quite so frustrating as spending an hour or more carefully researching the answer to an interesting question and composing a detailed response, only to have it bounce because my correspondent was sending from a public terminal and neglected to set the browser preferences to include their actual email address.

I also adhere to the old saying “If you like this book, tell your friends. If you don’t like it, tell me.” I’m especially interested in hearing about mistakes. This is my eighth book. I’ve yet to publish a perfect one, but I keep trying. As hard as I and the editors at O’Reilly worked on this book, I’m sure there are mistakes and typographical errors that we missed here somewhere. And I’m sure that at least one of them is a really embarrassing whopper of a problem. If you find a mistake or a typo, please let me know so I can correct it. I’ll post it on the O’Reilly website. Before reporting errors, please check one of those pages to see if I already know about it and have posted a fix. Any errors that are reported will be fixed in future printings.

Using Code Examples

This book is here to help you get your job done. In general, if this book includes code examples, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “JavaMail API by Elliotte Rusty Harold (O’Reilly). Copyright 2013 Elliotte Rusty Harold, 978-1-449-36724-4.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at [e-mail].

Safari® Books Online

Note

Safari Books Online is an on-demand digital library that delivers expert content in both book and video form from the world’s leading authors in technology and business.

Technology professionals, software developers, web designers, and business and creative professionals use Safari Books Online as their primary resource for research, problem solving, learning, and certification training.

Safari Books Online offers a range of product mixes and pricing programs for organizations, government agencies, and individuals. Subscribers have access to thousands of books, training videos, and prepublication manuscripts in one fully searchable database from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technology, and dozens more. For more information about Safari Books Online, please visit us online.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

O’Reilly Media, Inc.

1005 Gravenstein Highway North

Sebastopol, CA 95472

800-998-9938 (in the United States or Canada)

707-829-0515 (international or local)

707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at http://oreil.ly/javamail-api.

To comment or ask technical questions about this book, send email to [e-mail].

For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com.

Find us on Facebook: http://facebook.com/oreilly

Follow us on Twitter: http://twitter.com/oreillymedia

Watch us on YouTube: http://www.youtube.com/oreillymedia

Acknowledgments

Many people were involved in the production of this book.

Edward Wong, Alex Stangl, and Bill Shannon ably reviewed early drafts and substantially improved the coverage of many topics. Development editor Meghan Blanchette shepherded the book through the contract, writing, editing, and production process with grace and aplomb. It isn’t customary to thank the publisher, but the publisher does set the tone for the rest of the company, authors, editors, and production staff alike; and I think Tim O’Reilly deserves special credit for making O’Reilly Media absolutely one of the best houses an author can write for. If there’s one person without whom this book would never have been written, it’s him. If you, the reader, find O’Reilly books to be consistently better than most of the drek on the market, the reason really can be traced straight back to Tim.

Finally, as always, I’d like to offer my largest thanks for my wife, Beth, without whose love and support this book would never have happened.