- [HTTP request](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#body.HTTP_TEMPLATE)
- [Path parameters](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#body.PATH_PARAMETERS)
- [Query parameters](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#body.QUERY_PARAMETERS)
- [Request body](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#body.request_body)
- [Response body](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#body.response_body)
  - [JSON representation](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#body.ListHistoryResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#body.aspect)
- [HistoryType](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#HistoryType)
- [History](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#History)
  - [JSON representation](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#History.SCHEMA_REPRESENTATION)
- [MessageAdded](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#MessageAdded)
  - [JSON representation](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#MessageAdded.SCHEMA_REPRESENTATION)
- [MessageDeleted](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#MessageDeleted)
  - [JSON representation](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#MessageDeleted.SCHEMA_REPRESENTATION)
- [LabelAdded](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#LabelAdded)
  - [JSON representation](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#LabelAdded.SCHEMA_REPRESENTATION)
- [LabelRemoved](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#LabelRemoved)
  - [JSON representation](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#LabelRemoved.SCHEMA_REPRESENTATION)
- [Try it!](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#try-it)

Lists the history of all changes to the given mailbox. History results are returned in chronological order (increasing `historyId`). For more information, see [Synchronize clients with Gmail](https://developers.google.com/workspace/gmail/api/guides/sync).

### HTTP request

`GET https://gmail.googleapis.com/gmail/v1/users/{userId}/history`

The URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.

### Path parameters

| Parameters ||
|---|---|
| `userId` | `string` The user's email address. The special value `me` can be used to indicate the authenticated user. |

### Query parameters

| Parameters ||
|---|---|
| `maxResults` | `integer (https://developers.google.com/discovery/v1/type-format format)` Maximum number of history records to return. This field defaults to 100. The maximum allowed value for this field is 500. |
| `pageToken` | `string` Page token to retrieve a specific page of results in the list. |
| `startHistoryId` | `string` Required. Returns history records after the specified `startHistoryId`. The supplied `startHistoryId` should be obtained from the `historyId` of a message, thread, or previous `list` response. History IDs increase chronologically but are not contiguous with random gaps in between valid IDs. Supplying an invalid or out of date `startHistoryId` typically returns an `HTTP 404` error code. A `historyId` is typically valid for at least a week, but in some rare circumstances may be valid for only a few hours. If you receive an `HTTP 404` error response, your application should perform a full sync. If you receive no `nextPageToken` in the response, there are no updates to retrieve and you can store the returned `historyId` for a future request. |
| `labelId` | `string` Only return messages with a label matching the ID. |
| `historyTypes[]` | ``enum (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#HistoryType`)`` 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 (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#History`) } ], "nextPageToken": string, "historyId": string } ``` |

| Fields ||
|---|---|
| `history[]` | ``object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#History`)`` List of history records. Any `messages` contained in the response will typically only have `id` and `threadId` fields populated. |
| `nextPageToken` | `string` Page token to retrieve the next page of results in the list. |
| `historyId` | `string` 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](https://developers.google.com/workspace/guides/configure-oauth-consent).

## 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 (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages#Message`) } ], "messagesAdded": [ { object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#MessageAdded`) } ], "messagesDeleted": [ { object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#MessageDeleted`) } ], "labelsAdded": [ { object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#LabelAdded`) } ], "labelsRemoved": [ { object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#LabelRemoved`) } ] } ``` |

| Fields ||
|---|---|
| `id` | `string` The mailbox sequence ID. |
| `messages[]` | ``object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages#Message`)`` List of messages changed in this history record. The fields for specific change types, such as `messagesAdded` may duplicate messages in this field. We recommend using the specific change-type fields instead of this. |
| `messagesAdded[]` | ``object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#MessageAdded`)`` Messages added to the mailbox in this history record. |
| `messagesDeleted[]` | ``object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#MessageDeleted`)`` Messages deleted (not Trashed) from the mailbox in this history record. |
| `labelsAdded[]` | ``object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#LabelAdded`)`` Labels added to messages in this history record. |
| `labelsRemoved[]` | ``object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.history/list#LabelRemoved`)`` Labels removed from messages in this history record. |

## MessageAdded

| JSON representation |
|---|
| ``` { "message": { object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages#Message`) } } ``` |

| Fields ||
|---|---|
| `message` | ``object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages#Message`)`` |

## MessageDeleted

| JSON representation |
|---|
| ``` { "message": { object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages#Message`) } } ``` |

| Fields ||
|---|---|
| `message` | ``object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages#Message`)`` |

## LabelAdded

| JSON representation |
|---|
| ``` { "message": { object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages#Message`) }, "labelIds": [ string ] } ``` |

| Fields ||
|---|---|
| `message` | ``object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages#Message`)`` |
| `labelIds[]` | `string` Label IDs added to the message. |

## LabelRemoved

| JSON representation |
|---|
| ``` { "message": { object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages#Message`) }, "labelIds": [ string ] } ``` |

| Fields ||
|---|---|
| `message` | ``object (`https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages#Message`)`` |
| `labelIds[]` | `string` Label IDs removed from the message. |