This page describes hints and tips for using Jakarta Mail with Gmail. Basic
Gmail usage information can be found in the
Jakarta Mail FAQ.
Gmail users might want to read the
Gmail Help page.
The IMAP features page in Gmail Help no longer exists.
Previous versions (as viewable on the
indicated that Gmail does not support the following IMAP features.
(This list may no longer be accurate.)
\Recent flags on messages.
untagged FETCH responses.
Substring search. All searches are assumed to be words.
There is no SIEVE interface to Gmail filters.
Only AUTH=XOAUTH and plain-text LOGIN over SSL tunneled connections are supported.
ENVELOPE responses for email addresses in group syntax (RFC 5322 3.4)
The \Answered flag is not preserved when a message is moved or a label is added to the message.
To send email using Gmail with a different address than the one you
signed in with, see this
Gmail help page.
If the Gmail Auto-Expunge setting is turned on (the default),
when setting the \Deleted flag on a message, Gmail will expunge
the message, causing it to disappear from the mailbox.
Gmail also includes a setting to control what happens to deleted
and expunged messages (including auto-expunged messages). They
can be archived (left in the [Gmail]/All Mail folder), moved to
the [Gmail]/Trash folder, or removed completely. The default is
to archive the message.
As of Mar 21, 2011, an old Gmail bug has returned. When reading an
attachment, Gmail fails to return all of the data. This occurs because
Gmail reports the wrong size for the attachment in the BODYSTRUCTURE
response. It reports the size using Unix line terminators instead of
the required MIME line terminators. The bug has been reported to
As of Dec 2011, several users have reported an
ArrayIndexOutOfBoundsException when accessing some messages in Gmail.
This is a bug in Gmail involving Subject headers with embedded
newlines. Google expects a fix to be available in mid March 2012.
As of Jan 2012, Gmail has a bug that causes it to fail to return a
valid IMAP BODYSTRUCTURE response for messages that include another
message as an attachment. Applications may see an exception with a
message of “ENVELOPE parse error”. The
workaround described in the Jakarta Mail FAQ
can be helpful for dealing with such messages. JavaMail 1.4.5 includes
a workaround for this Gmail bug.
As of Dec 2012, Gmail has a bug that causes it to return a different
value for the getMessageID method than is in the Message-Id header of a
message. The returned Message-Id is “canonicalized”. If you need the
actual value in the header, use the getHeader method instead. Google
has no current plans to fix this bug.
As of Jan 2014, Gmail still only notifies clients of new messages and
expunged messages when using IMAP IDLE. Other flag changes are not
As of Aug 2014, Gmail moves expunged messages to the Trash folder.
They’re only really removed if expunged from Trash.