- HTTP request
- Path parameters
- Query parameters
- Request body
- Response body
- Authorization scopes
- HistoryType
- History
- MessageAdded
- MessageDeleted
- LabelAdded
- LabelRemoved
- Try it!
Lists the history of all changes to the given mailbox. History results are returned in chronological order (increasing historyId
).
HTTP request
GET https://gmail.googleapis.com/gmail/v1/users/{userId}/history
The URL uses gRPC Transcoding syntax.
Path parameters
Parameters | |
---|---|
userId |
The user's email address. The special value |
Query parameters
Parameters | |
---|---|
maxResults |
Maximum number of history records to return. This field defaults to 100. The maximum allowed value for this field is 500. |
pageToken |
Page token to retrieve a specific page of results in the list. |
startHistoryId |
Required. Returns history records after the specified |
labelId |
Only return messages with a label matching the ID. |
historyTypes[] |
History types to be returned by the function |
Request body
The request body must be empty.
Response body
If successful, the response body contains data with the following structure:
JSON representation |
---|
{
"history": [
{
object ( |
Fields | |
---|---|
history[] |
List of history records. Any |
nextPageToken |
Page token to retrieve the next page of results in the list. |
historyId |
The ID of the mailbox's current history record. |
Authorization scopes
Requires one of the following OAuth scopes:
https://mail.google.com/
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.metadata
For more information, see the Authorization guide.
HistoryType
Enums | |
---|---|
messageAdded |
|
messageDeleted |
|
labelAdded |
|
labelRemoved |
History
A record of a change to the user's mailbox. Each history change may affect multiple messages in multiple ways.
JSON representation |
---|
{ "id": string, "messages": [ { object ( |
Fields | |
---|---|
id |
The mailbox sequence ID. |
messages[] |
List of messages changed in this history record. The fields for specific change types, such as |
messagesAdded[] |
Messages added to the mailbox in this history record. |
messagesDeleted[] |
Messages deleted (not Trashed) from the mailbox in this history record. |
labelsAdded[] |
Labels added to messages in this history record. |
labelsRemoved[] |
Labels removed from messages in this history record. |
MessageAdded
JSON representation |
---|
{
"message": {
object ( |
Fields | |
---|---|
message |
|
MessageDeleted
JSON representation |
---|
{
"message": {
object ( |
Fields | |
---|---|
message |
|
LabelAdded
JSON representation |
---|
{
"message": {
object ( |
Fields | |
---|---|
message |
|
labelIds[] |
Label IDs added to the message. |
LabelRemoved
JSON representation |
---|
{
"message": {
object ( |
Fields | |
---|---|
message |
|
labelIds[] |
Label IDs removed from the message. |