List

Lists the history of all changes to the given mailbox

6 variables
24 variables

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

Authorization

To use this building block you will have to grant access to at least one of the following scopes:

  • Read, compose, send, and permanently delete all your email from Gmail
  • View your email message metadata such as labels and headers, but not the email body
  • View and modify but not delete your email
  • View your email messages and settings

Input

This building block consumes 6 input parameters

  = Parameter name
  = Format

userId STRING Required

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

historyTypes ENUMERATION

History types to be returned by the function

labelId STRING

Only return messages with a label matching the ID

maxResults INTEGER

The maximum number of history records to return

pageToken STRING

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

startHistoryId INTEGER

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

Output

This building block provides 24 output parameters

  = Parameter name
  = Format

history[] OBJECT

A record of a change to the user's mailbox. Each history change may affect multiple messages in multiple ways

history[].id INTEGER

The mailbox sequence ID

history[].labelsAdded[] OBJECT

history[].labelsAdded[].labelIds[] STRING

history[].labelsAdded[].message OBJECT

An email message

history[].labelsRemoved[] OBJECT

history[].labelsRemoved[].labelIds[] STRING

history[].labelsRemoved[].message OBJECT

An email message

history[].messages[] OBJECT

An email message

history[].messages[].historyId INTEGER

The ID of the last history record that modified this message

history[].messages[].id STRING

The immutable ID of the message

history[].messages[].internalDate INTEGER

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

history[].messages[].labelIds[] STRING

history[].messages[].payload OBJECT

A single MIME message part

history[].messages[].raw BINARY

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

history[].messages[].sizeEstimate INTEGER

Estimated size in bytes of the message

history[].messages[].snippet STRING

A short part of the message text

history[].messages[].threadId STRING

The ID of the thread the message belongs to. To add a message or draft to a thread, the following criteria must be met:

  • The requested threadId must be specified on the Message or Draft.Message you supply with your request.
  • The References and In-Reply-To headers must be set in compliance with the RFC 2822 standard.
  • The Subject headers must match.

history[].messagesAdded[] OBJECT

history[].messagesAdded[].message OBJECT

An email message

history[].messagesDeleted[] OBJECT

history[].messagesDeleted[].message OBJECT

An email message

historyId INTEGER

The ID of the mailbox's current history record

nextPageToken STRING

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