Google: Lists the history of all changes to the given mailbox History results are returned in chronological order (increasing `history Id`) For more information, see Synchronize clients with Gmail (https: developers google com workspace gmail api guides sync)
Google gmailUsersHistory.gmailUsersHistoryList: arguments, response, policy and SDK examples.
← Gmail users history operations · Get started
Operation google.gmail_users_history_list
Provider route: GET /gmail/v1/users/{userId}/history. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/google with npm, or alter-sdk-google with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { GoogleIntegration } from "@alter-ai/google";
async function execute(input: Parameters<GoogleIntegration["gmailUsersHistory"]["gmailUsersHistoryList"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new GoogleIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.gmailUsersHistory.gmailUsersHistoryList(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_google import GoogleIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = GoogleIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.gmail_users_history.gmail_users_history_list(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.userId | string | Required within parent | The user’s email address. The special value `me` can be used to indicate the authenticated user. Default: me |
query | object | Required within parent | Additional keys: not allowed |
query.fields | string | Optional | Selector specifying which fields to include in a partial response. |
query.prettyPrint | boolean | Optional | Returns response with indentations and line breaks. Default: true |
query.quotaUser | string | Optional | 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. |
query.historyTypes | array | Optional | |
query.historyTypes[] | string | Each item | History types to be returned by the function One of: messageAdded, messageDeleted, labelAdded, labelRemoved |
query.labelId | string | Optional | Only return messages with a label matching the ID. |
query.maxResults | integer | Optional | Maximum number of history records to return. This field defaults to 100. The maximum allowed value for this field is 500. Default: 100 Format: uint32 |
query.pageToken | string | Optional | Page token to retrieve a specific page of results in the list. |
query.startHistoryId | string | Required within parent | 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. Format: uint64 |
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
Schemas
Section titled “Schemas”5 more schemas are linked from the tables above, on the schema pages.
Lists the history of all changes to the given mailbox History results are returned in chronological order (increasing `history Id`) For more information, see Synchronize clients with Gmail (https: developers google com workspace gmail api guides sync) — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
history | array | Optional | List of history records. Any `messages` contained in the response will typically only have `id` and `threadId` fields populated. |
history[] | Model | Each item | Expand Lists the history of all changes to the given mailbox History results are returned in chronological order (increasing `history Id`) For more information, see Synchronize clients with Gmail (https: developers google com workspace gmail api guides sync) — response body — history item |
historyId | string | Optional | The ID of the mailbox's current history record. Format: uint64 |
nextPageToken | string | Optional | Page token to retrieve the next page of results in the list. |
Lists the history of all changes to the given mailbox History results are returned in chronological order (increasing `history Id`) For more information, see Synchronize clients with Gmail (https: developers google com workspace gmail api guides sync) — response body — history item
Referenced models: Lists the history of all changes to the given mailbox History results are returned in chronological order (increasing `history Id`) For more information, see Synchronize clients with Gmail (https: developers google com workspace gmail api guides sync) — response body — history item labels Added item, Lists the history of all changes to the given mailbox History results are returned in chronological order (increasing `history Id`) For more information, see Synchronize clients with Gmail (https: developers google com workspace gmail api guides sync) — response body — history item labels Removed item, Lists the history of all changes to the given mailbox History results are returned in chronological order (increasing `history Id`) For more information, see Synchronize clients with Gmail (https: developers google com workspace gmail api guides sync) — response body — history item messages Added item, Gets the specified message — response body
Lists the history of all changes to the given mailbox History results are returned in chronological order (increasing `history Id`) For more information, see Synchronize clients with Gmail (https: developers google com workspace gmail api guides sync) — response body — history item labels Added item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
labelIds | array | Optional | Label IDs added to the message. |
labelIds[] | string | Each item | |
message | Model | Optional | Expand Gets the specified message — response body |
Referenced models: Gets the specified message — response body
Lists the history of all changes to the given mailbox History results are returned in chronological order (increasing `history Id`) For more information, see Synchronize clients with Gmail (https: developers google com workspace gmail api guides sync) — response body — history item labels Removed item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
labelIds | array | Optional | Label IDs removed from the message. |
labelIds[] | string | Each item | |
message | Model | Optional | Expand Gets the specified message — response body |
Referenced models: Gets the specified message — response body
Lists the history of all changes to the given mailbox History results are returned in chronological order (increasing `history Id`) For more information, see Synchronize clients with Gmail (https: developers google com workspace gmail api guides sync) — response body — history item messages Added item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
message | Model | Optional | Expand Gets the specified message — response body |
Referenced models: Gets the specified message — response body
Gets the specified message — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | An email message. |
classificationLabelValues | array | Optional | Classification Label values on the message. Available Classification Label schemas can be queried using the Google Drive Labels API. Each classification label ID must be unique. If duplicate IDs are provided, only one will be retained, and the selection is arbitrary. Only used for Google Workspace accounts. There's a limit of 20 Classification Label values per request. If the Classification Label values exceeds the maximum allowed number, the request fails. |
classificationLabelValues[] | Model | Each item | Expand Gets the specified message — response body — classification Label Values item |
historyId | string | Optional | The ID of the last history record that modified this message. Format: uint64 |
id | string | Optional | The immutable ID of the message. |
internalDate | string | Optional | The internal message creation timestamp (epoch ms), which determines ordering in the inbox. For normal SMTP-received email, this represents the time the message was originally accepted by Google, which is more reliable than the `Date` header. However, for API-migrated mail, it can be configured by client to be based on the `Date` header. Format: int64 |
labelIds | array | Optional | List of IDs of labels applied to this message. |
labelIds[] | string | Each item | |
payload | Model | Optional | Expand Gets the specified message — response body — payload The parsed email structure in the message parts. |
raw | string | Optional | The entire email message in an RFC 2822 formatted and base64url encoded string. Returned in `messages.get` and `drafts.get` responses when the `format=RAW` parameter is supplied. @required gmail.users.drafts.create gmail.users.drafts.update Format: byte |
sizeEstimate | JSON | Optional | |
sizeEstimate (anyOf 1) | integer | Alternative | Estimated size in bytes of the message. Format: int32 |
sizeEstimate (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
snippet | string | Optional | A short part of the message text. |
threadId | string | Optional | The ID of the thread the message belongs to. To add a message or draft to a thread, the following criteria must be met: 1. The requested `threadId` must be specified on the `Message` or `Draft.Message` you supply with your request. 2. The `References` and `In-Reply-To` headers must be set in compliance with the [RFC 2822](https://tools.ietf.org/html/rfc2822) standard. 3. The `Subject` headers must match. |
Referenced models: Gets the specified message — response body — classification Label Values item, Gets the specified message — response body — payload
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: google.gmail_users_history_list. Catalog operation: gmail.users.history.list. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["https://mail.google.com/", "https://www.googleapis.com/auth/gmail.metadata", "https://www.googleapis.com/auth/gmail.modify", "https://www.googleapis.com/auth/gmail.readonly"]