# com.sun.mail.gimap package

An EXPERIMENTAL IMAP protocol provider that supports the Gmail-specific IMAP protocol extensions . This provider supports all the features of the IMAP provider, plus additional Gmail-specific features. This provider can be used by including gimap.jar in your CLASSPATH along with mail.jar, and by using the "gimap" protocol instead of the "imap" protocol. Remember that this means that all properties should be named "mail.gimap.*", but that otherwise this provider supports all the same properties as the IMAP protocol provider. The Gmail IMAP provider defaults to using SSL to connect to "imap.gmail.com".

In general, applications should not need to use the classes in this package directly. Instead, they should use the APIs defined by the `javax.mail` package (and subpackages). Applications should never construct instances of `GmailStore` or `GmailFolder` directly. Instead, they should use the `Session` method `getStore` to acquire an appropriate `Store` object, and from that acquire `Folder` objects.

Message objects returned by this provider may be cast to GmailMessage to access Gmail-specific data, e.g., using the methods GmailMessage.getMsgId(), GmailMessage.getThrId(), and GmailMessage.getLabels(). For example:

        GmailMessage gmsg = (GmailMessage)msg;
        System.out.println("Gmail message ID is " + gmsg.getMsgId());
        String[] labels = gmsg.getLabels();
        for (String s : labels)
    	System.out.println("Gmail message label: " + s);

Gmail-specific data may be prefetched using the GmailFolder.FetchProfileItems MSGID, THRID, and LABELS. For example:

        FetchProfile fp = new FetchProfile();
        fp.add(GmailFolder.FetchProfileItem.MSGID);
        folder.fetch(fp);

You can search using Gmail-specific data using the GmailMsgIdTerm, GmailThrIdTerm, and GmailRawSearchTerm search terms. For example:

        // find the message with this Gmail unique message ID
        long msgid = ...;
        Message[] msgs = folder.search(new GmailMsgIdTerm(msgid));

You can access the Gmail extended attributes (returned by XLIST) for a folder using the IMAPFolder.getAttributes() method. For example:

        IMAPFolder ifolder = (IMAPFolder)folder;
        String[] attrs = ifolder.getAttributes();
        for (String s : attrs)
    	System.out.println("Folder attribute: " + s);

WARNING: The APIs unique to this package should be considered EXPERIMENTAL. They may be changed in the future in ways that are incompatible with applications using the current APIs.