Search a JavaMail mailbox for unseen messages

While working on a Java application yesterday, I ran into a situation where I needed to search my POP3 mailbox for unseen messages, i.e., email messages I haven't read yet. (I'm adding some "You've got mail" functionality to one of my automated robots.)

Jumping right to the solution, here's the complete source code for a JavaMail example class that demonstrates how to search for unseen (unread) email messages in a POP/POP3 mailbox:

package javamailtests;

import java.util.Calendar;
import java.util.GregorianCalendar;
import java.util.Properties;
import javax.mail.*;
import javax.mail.internet.*;

public class JavaMailSearchInbox {

  public static void main(String args[]) throws Exception {

    // mail server info
    String host = "";
    String user = "USER";
    String password = "PASS";

    // connect to my pop3 inbox in read-only mode
    Properties properties = System.getProperties();
    Session session = Session.getDefaultInstance(properties);
    Store store = session.getStore("pop3");
    store.connect(host, user, password);
    Folder inbox = store.getFolder("inbox");;

    // search for all "unseen" messages
    Flags seen = new Flags(Flags.Flag.SEEN);
    FlagTerm unseenFlagTerm = new FlagTerm(seen, false);
    Message messages[] =;
    if (messages.length == 0) System.out.println("No messages found.");

    for (int i = 0; i < messages.length; i++) {
      // stop after listing ten messages
      if (i > 10) {

      System.out.println("Message " + (i + 1));
      System.out.println("From : " + messages[i].getFrom()[0]);
      System.out.println("Subject : " + messages[i].getSubject());
      System.out.println("Sent Date : " + messages[i].getSentDate());


As you can tell, the magic in that example is in these lines of code:

// search for all "unseen" messages
Flags seen = new Flags(Flags.Flag.SEEN);
FlagTerm unseenFlagTerm = new FlagTerm(seen, false);
Message messages[] =;

In this code, the Flags and FlagTerm classes come from the JavaMail search package (the* import statement). What I'm doing in the first and second lines of code are to create a search term where the SEEN property is set to false, meaning that I'm looking for email messages I haven't seen (or haven't read).

As I've mentioned in earlier JavaMail tutorials, if you have a really large mailbox, you can get a very large list of email messages returned with a search query like this, so I've put a limit inside the for loop to print only the first ten messages returned.

The JavaMail search API is very powerful, and this is really just a small example of what you can do. For instance, you can combine JavaMail search terms like this:

SearchTerm searchTerm = new AndTerm(unseenFlagTerm, lastTwoDaysTerm);
Message[] messages =;

I hope to share powerful mailbox search examples like this in future JavaMail tutorials, but until then, I hope this simple inbox search example -- and this preview of how to search using multiple search terms -- has been helpful.

Share it!

There’s just one person behind this website; if this article was helpful (or interesting), I’d appreciate it if you’d share it. Thanks, Al.

Add new comment

The content of this field is kept private and will not be shown publicly.

Anonymous format

  • Allowed HTML tags: <em> <strong> <cite> <code> <ul type> <ol start type> <li> <pre>
  • Lines and paragraphs break automatically.
By submitting this form, you accept the Mollom privacy policy.