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.

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.