Gmail.users.history.list

Lists the history of all changes to the given mailbox. History results are returned in chronological order (increasing `historyId`).

GET/gmail/v1/users/{userId}/history

Use it in a workflow

Add a step and choose the Gmail connector.
Pick the Gmail.users.history.list action (under users).
Fill in the fields below, then reference the result from later steps as {{gmailUsersHistoryList.response.data}}.

Request

Path parameters

userIdstringrequired

The user's email address. The special value `me` can be used to indicate the authenticated user.

Query parameters

$.xgafvstring

V1 error format.

One of12

access_tokenstring

OAuth access token.

altstring

Data format for response.

One ofjsonmediaproto

callbackstring

JSONP

fieldsstring

Selector specifying which fields to include in a partial response.

keystring

API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.

oauth_tokenstring

OAuth 2.0 token for the current user.

prettyPrintboolean

Returns response with indentations and line breaks.

quotaUserstring

Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.

upload_protocolstring

Upload protocol for media (e.g. "raw", "multipart").

uploadTypestring

Legacy upload protocol for media (e.g. "media", "multipart").

historyTypesarray<string>

History types to be returned by the function

labelIdstring

Only return messages with a label matching the ID.

maxResultsinteger

Maximum number of history records to return. This field defaults to 100. The maximum allowed value for this field is 500.

pageTokenstring

Page token to retrieve a specific page of results in the list.

startHistoryIdstring

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.

Response

Returns 200 with an object. Read it in later steps with {{gmailUsersHistoryList.response.data.<field>}}.

historyarray<object>

List of history records. Any `messages` contained in the response will typically only have `id` and `threadId` fields populated.

idstring (uint64)

The mailbox sequence ID.

labelsAddedarray<object>2 fields

Labels added to messages in this history record.

labelsRemovedarray<object>2 fields

Labels removed from messages in this history record.

messagesarray<object>9 fields

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.

messagesAddedarray<object>1 fields

Messages added to the mailbox in this history record.

messagesDeletedarray<object>1 fields

Messages deleted (not Trashed) from the mailbox in this history record.

historyIdstring (uint64)

The ID of the mailbox's current history record.

nextPageTokenstring

Page token to retrieve the next page of results in the list.

json

{
  "history": [
    {
      "id": "string",
      "labelsAdded": [
        {
          "labelIds": [
            "string"
          ],
          "message": {
            "historyId": "string",
            "id": "string",
            "internalDate": "string",
            "labelIds": [
              null
            ],
            "payload": {
              "body": null,
              "filename": null,
              "headers": null,
              "mimeType": null,
              "partId": null,
              "parts": null
            },
            "raw": "string",
            "sizeEstimate": 0,
            "snippet": "string",
            "threadId": "string"
          }
        }
      ],
      "labelsRemoved": [
        {
          "labelIds": [
            "string"
          ],
          "message": {
            "historyId": "string",
            "id": "string",
            "internalDate": "string",
            "labelIds": [
              null
            ],
            "payload": {
              "body": null,
              "filename": null,
              "headers": null,
              "mimeType": null,
              "partId": null,
              "parts": null
            },
            "raw": "string",
            "sizeEstimate": 0,
            "snippet": "string",
            "threadId": "string"
          }
        }
      ],
      "messages": [
        {
          "historyId": "string",
          "id": "string",
          "internalDate": "string",
          "labelIds": [
            "string"
          ],
          "payload": {
            "body": {
              "attachmentId": null,
              "data": null,
              "size": null
            },
            "filename": "string",
            "headers": [
              null
            ],
            "mimeType": "string",
            "partId": "string",
            "parts": [
              null
            ]
          },
          "raw": "string",
          "sizeEstimate": 0,
          "snippet": "string",
          "threadId": "string"
        }
      ],
      "messagesAdded": [
        {
          "message": {
            "historyId": "string",
            "id": "string",
            "internalDate": "string",
            "labelIds": [
              null
            ],
            "payload": {
              "body": null,
              "filename": null,
              "headers": null,
              "mimeType": null,
              "partId": null,
              "parts": null
            },
            "raw": "string",
            "sizeEstimate": 0,
            "snippet": "string",
            "threadId": "string"
          }
        }
      ],
      "messagesDeleted": [
        {
          "message": {
            "historyId": "string",
            "id": "string",
            "internalDate": "string",
            "labelIds": [
              null
            ],
            "payload": {
              "body": null,
              "filename": null,
              "headers": null,
              "mimeType": null,
              "partId": null,
              "parts": null
            },
            "raw": "string",
            "sizeEstimate": 0,
            "snippet": "string",
            "threadId": "string"
          }
        }
      ]
    }
  ],
  "historyId": "string",
  "nextPageToken": "string"
}

Need more? See the Gmail guide for connection setup and behaviour shared by every action.

Was this page helpful?