Google: Gmail users messages schemas
13 Google schemas with complete fields and constraints.
← Gmail users messages operations · All schemas
Deletes many messages by message ID Provides no guarantees that messages were not already deleted or even existed at all — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
ids | array | Optional | The IDs of the messages to delete. |
ids[] | string | Each item |
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
Gets the specified message — response body — classification Label Values item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Classification Labels applied to the email message. Classification Labels are different from Gmail inbox labels. Only used for Google Workspace accounts. [Learn more about classification labels](https://support.google.com/a/answer/9292382). |
fields | array | Optional | Field values for the given classification label ID. |
fields[] | Model | Each item | Expand Gets the specified message — response body — classification Label Values item fields item |
labelId | string | Optional | Required. The canonical or raw alphanumeric classification label ID. Maps to the ID field of the Google Drive Label resource. |
Referenced models: Gets the specified message — response body — classification Label Values item fields item
Gets the specified message — response body — classification Label Values item fields item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Field values for a classification label. |
fieldId | string | Optional | Required. The field ID for the Classification Label Value. Maps to the ID field of the Google Drive `Label.Field` object. |
selection | string | Optional | Selection choice ID for the selection option. Should only be set if the field type is `SELECTION` in the Google Drive `Label.Field` object. Maps to the id field of the Google Drive `Label.Field.SelectionOptions` resource. |
Gets the specified message — response body — payload
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A single MIME message part. |
body | Model | Optional | Expand Gets the specified message attachment — response body The message part body for this part, which may be empty for container MIME message parts. |
filename | string | Optional | The filename of the attachment. Only present if this message part represents an attachment. |
headers | array | Optional | List of headers on this message part. For the top-level message part, representing the entire message payload, it will contain the standard RFC 2822 email headers such as `To`, `From`, and `Subject`. |
headers[] | Model | Each item | Expand Gets the specified message — response body — payload headers item |
mimeType | string | Optional | The MIME type of the message part. |
partId | string | Optional | The immutable ID of the message part. |
parts | array | Optional | The child MIME message parts of this part. This only applies to container MIME message parts, for example `multipart/*`. For non- container MIME message part types, such as `text/plain`, this field is empty. For more information, see RFC 1521. |
parts[] | Model | Each item | Expand Gets the specified message — response body — payload |
Referenced models: Gets the specified message — response body — payload, Gets the specified message attachment — response body, Gets the specified message — response body — payload headers item
Gets the specified message — response body — payload headers item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
name | string | Optional | The name of the header before the `:` separator. For example, `To`. |
value | string | Optional | The value of the header after the `:` separator. For example, `someuser@example.com`. |
Imports a message into only this user's mailbox, with standard email delivery scanning and classification similar to receiving via SMTP This method doesn't perform SPF checks, so it might not work for some spam messages, such as those attempting to perform domain spoofing This method does not send a message Note that the maximum size of the message is 150 MB — request body — 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 Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — 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 | integer | Optional | Estimated size in bytes of the message. Format: int32 |
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, Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — body payload
Lists the messages in the user's mailbox For more information, see List Gmail messages (https: developers google com workspace gmail api guides list-messages) — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
messages | array | Optional | List of messages. Note that each message resource contains only an `id` and a `threadId`. Additional message details can be fetched using the messages.get method. |
messages[] | Model | Each item | Expand Gets the specified message — response body |
nextPageToken | string | Optional | Token to retrieve the next page of results in the list. |
resultSizeEstimate | JSON | Optional | |
resultSizeEstimate (anyOf 1) | integer | Alternative | Estimated total number of results. Format: uint32 |
resultSizeEstimate (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Referenced models: Gets the specified message — response body
Modifies the labels and the Classification Label values on the specified message For administrators modifying message for users in their organization, requests require authorization with a service account (https: developers google com identity protocols O Auth2 Service Account) that has domain-wide delegation authority (https: developers google com identity protocols O Auth2 Service Account#delegatingauthority) to impersonate users with the `https: www googleapis com auth gmail modify restricted` scope — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
addClassificationLabels | array | Optional | A list of classification label values to add. If a Classification Label with the same label ID is already applied to the message, fields with existing field IDs will be updated and fields with new field IDs will be added. There's a limit of 20 Classification Label values per request. If the message is already classified and the final total number of Classification Label values exceeds the maximum allowed number of Classification Label values per message, the modification fails. |
addClassificationLabels[] | Model | Each item | Expand Gets the specified message — response body — classification Label Values item |
addLabelIds | array | Optional | A list of IDs of labels to add to this message. You can add up to 100 labels with each update. |
addLabelIds[] | string | Each item | |
removeClassificationLabelIds | array | Optional | A list of Classification Label values to remove from this message. |
removeClassificationLabelIds[] | string | Each item | |
removeLabelIds | array | Optional | A list IDs of labels to remove from this message. You can remove up to 100 labels with each update. |
removeLabelIds[] | string | Each item |
Referenced models: Gets the specified message — response body — classification Label Values item
Modifies the labels and the Classification Label values on the specified messages For administrators modifying messages for users in their organization, requests require authorization with a service account (https: developers google com identity protocols O Auth2 Service Account) that has domain-wide delegation authority (https: developers google com identity protocols O Auth2 Service Account#delegatingauthority) to impersonate users with the `https: www googleapis com auth gmail modify restricted` scope — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
addClassificationLabels | array | Optional | A list of Classification Label values to add. If a Classification Label with the same label ID is already applied to the message, fields with existing field IDs will be updated and fields with new field IDs will be added. There's a limit of 20 Classification Label values per request. If the message is already classified and the final total number of Classification Label values exceeds the maximum allowed number of Classification Label values per message, the modification fails. |
addClassificationLabels[] | Model | Each item | Expand Gets the specified message — response body — classification Label Values item |
addLabelIds | array | Optional | A list of label IDs to add to messages. |
addLabelIds[] | string | Each item | |
ids | array | Optional | The IDs of the messages to modify. There is a limit of 1000 ids per request. |
ids[] | string | Each item | |
removeClassificationLabelIds | array | Optional | A list of Classification Label values to remove from messages. |
removeClassificationLabelIds[] | string | Each item | |
removeLabelIds | array | Optional | A list of label IDs to remove from messages. |
removeLabelIds[] | string | Each item |
Referenced models: Gets the specified message — response body — classification Label Values item
Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — 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 Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — body payload The parsed email structure in the message parts. |
raw | string | Required within parent | 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 | integer | Optional | Estimated size in bytes of the message. Format: int32 |
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, Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — body payload
Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — body payload
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A single MIME message part. |
body | Model | Optional | Expand Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — body payload body The message part body for this part, which may be empty for container MIME message parts. |
filename | string | Optional | The filename of the attachment. Only present if this message part represents an attachment. |
headers | array | Optional | List of headers on this message part. For the top-level message part, representing the entire message payload, it will contain the standard RFC 2822 email headers such as `To`, `From`, and `Subject`. |
headers[] | Model | Each item | Expand Gets the specified message — response body — payload headers item |
mimeType | string | Optional | The MIME type of the message part. |
partId | string | Optional | The immutable ID of the message part. |
parts | array | Optional | The child MIME message parts of this part. This only applies to container MIME message parts, for example `multipart/*`. For non- container MIME message part types, such as `text/plain`, this field is empty. For more information, see RFC 1521. |
parts[] | Model | Each item | Expand Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — body payload |
Referenced models: Gets the specified message — response body — payload headers item, Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — body payload, Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — body payload body
Sends the specified message to the recipients in the `To`, `Cc`, and `Bcc` headers For more information, see Create and send email messages (https: developers google com workspace gmail api guides sending) — request body — body payload body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The body of a single MIME message part. |
attachmentId | string | Optional | When present, contains the ID of an external attachment that can be retrieved in a separate `messages.attachments.get` request. When not present, the entire content of the message part body is contained in the data field. |
data | string | Optional | The body data of a MIME message part as a base64url encoded string. May be empty for MIME container types that have no message body or when the body data is sent as a separate attachment. An attachment ID is present if the body data is contained in a separate attachment. Format: byte |
size | integer | Optional | Number of bytes for the message part data (encoding notwithstanding). Format: int32 |