This page contains release notes for the Gmail API.
12 November 2019 New message.import() implementation
messages.import() is now
implemented using a more performant backend implementation. The new version
is API-compatible with the previous implementation and all clients automatically
started using the new behavior as of a few weeks ago. The new backend
message.import() calls efficiently and clients can now
import messages in parallel for a user to achieve higher migration throughput.
The quota cost of the message.import() API method has been decreased to reflect
the new performance.
7 Febuary 2017 History type filtering for history.list()
history.list() now supports
filtering history records by type.
30 November 2016 New messages.batchModify() method
is a new method that allows modifying labels on multiple messages by message
IDs, in a single batch operation.
1 November 2016: New metadata scope
The Gmail API now supports a new gmail.metadata scope. This scope gives developers acccess to a user's mailbox including history records, labels, and email headers, but not email body's or attachments.
1 July 2016: New endpoints for settings
We've introduced several new endpoints for managing mail settings. Refer to the following guides for details:
drafts.list() has a new
q, that restricts results to just the messages matching the
25 February 2016: New messages.batchDelete() method
is a new method that allows deleting multiple messages, by message IDs, in
a single batch operation.
13 January 2016: New Option for drafts.list()
drafts.list() now has a new
option, includeSpamTrash, which is used to determine if the response should
include drafts with the SPAM or TRASH label applied. The default is currently
set to true for this option, but we plan on switching it to false shortly.
22 June 2015: Labels from history.list()
returns all current
Message.labelIds as part of the response in
so it's easy to determine full state of an email before and after a change.
18 June 2015: Message internalDate field
Added a new
field that exposes the message's creation timestamp in the mailbox.
29 May 2015: Gmail API push notifications
The Gmail API now supports sending push notifications on mailbox updates, providing real-time server notification without the need for constant polling. Utilizing Cloud Pub/Sub you can now use webhooks, for example, to receive callbacks when updates happen. Additionally, these notifications can be filtered to specific Gmail labels. See the push notifications guide to get started.
31 March 2015: New scopes for labels and inserting messages
We've introduced two new, finer-grained ACL scopes to better protect users and accomodate apps that don't need full mailbox data access:
all label operationsonly.
18 March 2015: New options to messages insert
deleted request parameter and allows setting
25 February 2015: More details from history list
history.list() now provides
details of the change type in each history record. For example, using
it's possible to easily tell how a message was changed and
typically avoids the need for additional calls to synchronize your client.
11 February 2015: New options to messages import
supports three new parameters to better support
Email Migration use cases. See the
for how to use the new
23 January 2015: Message import labels support and default change
You can now specify
to automatically apply the given labels to the message.
Consequentially, in the next few weeks the default behavior will change to stop
UNREAD labels to
message.labelIds is not specified imported mail will only be visible in
All Mail. If you want
UNREAD labels applied, please specify
them in the
15 January 2015: Per-user quotas increased
per-user quotas have been increased
from 25 units/user/second to 250 units/user/second and some method costs have
been adjusted slightly.
22 October 2014: New format parameter for retrieving threads
You can now specify the return format for the
threads.get(). The available
minimal, similar to the
method. Note that
raw format is not allowed for
threads.get() to avoid
unexpectedly large amounts of data being returned.
16 October 2014: New GetProfile method
getProfile() method is now
available. It provides mailbox-wide info like current history ID and total
message and thread counts.
6 October 2014: A new IMPORTANT label and new fields for counting messages with a given label
We've added a new
IMPORTANT label to
match functionality with the Gmail web interface.
Additionally, we've added four new fields to the Labels resource to simplify counting how many messages have a given label applied.
The new fields are:
8 September 2014: New message format available
We've made some changes to
messages.get(). You can
now request the
metadata return format to return only the email headers
and metadata such as identifiers and labels.
2 September 2014: Change to internal date behavior
You can now specify the
internalDateSource for both
We'd like to switch the default behavior for this flag to be something more
intuitive and intend to change the default behavior on September 15th, 2014.
After that point
messages.insert() will default to using
messages.import() will default to using
dateHeader. If you care about
the internal date source for
make sure you start specifying this request query parameter before then.
11 July 2014: Update to method quota costs
Quota costs for all methods in the API have been reduced by a factor of 10. For example, if a method previously cost 150 quota units, it now costs 15. For a complete list of API method costs, see the per-method quota usage chart.
25 June 25 2014: Gmail API is released!
The Gmail API is now publicly available!