Gmail API

/gmail/v1/users/{userId}/messages

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

Lists the messages in the user's mailbox.

Request

Path Params

userId

string

required

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

Query Params

includeSpamTrash

string

optional

Include messages from SPAM and TRASH in the results.

labelIds

array[string]

optional

Only return messages with labels that match all of the specified label IDs. Messages in a thread might have labels that other messages in the same thread don't have. To learn more, see Manage labels on messages and threads.

maxResults

integer

optional

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

pageToken

string

optional

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

string

optional

Only return messages matching the specified query. Supports the same query format as the Gmail search box. For example, "from:someuser@example.com rfc822msgid: is:unread". Parameter cannot be used when accessing the api using the gmail.metadata scope.

Request samples

Responses

Successful response(200)

Successful response

HTTP Code: 200

Content Type : JSONapplication/json

messages

array[object (Message) {9}]

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.

historyId

string <uint64>

optional

The ID of the last history record that modified this message.

string

optional

The immutable ID of the message.

internalDate

string <int64>

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.

labelIds

array[string]

optional

List of IDs of labels applied to this message.

payload

object (MessagePart)

optional

The parsed email structure in the message parts.

raw

string <byte>

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.

sizeEstimate

integer <int32>

optional

Estimated size in bytes of the message.

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 standard. 3. The Subject headers must match.

nextPageToken

string

optional

Token to retrieve the next page of results in the list.

resultSizeEstimate

integer <uint32>

optional

Estimated total number of results.

{
  "messages": [
    {
      "historyId": "string",
      "id": "string",
      "internalDate": "string",
      "labelIds": [
        "string"
      ],
      "payload": {
        "body": {
          "attachmentId": "string",
          "data": "string",
          "size": 0
        },
        "filename": "string",
        "headers": [
          {
            "name": "string",
            "value": "string"
          }
        ],
        "mimeType": "string",
        "partId": "string",
        "parts": [
          {}
        ]
      },
      "raw": "string",
      "sizeEstimate": 0,
      "snippet": "string",
      "threadId": "string"
    }
  ],
  "nextPageToken": "string",
  "resultSizeEstimate": 0
}

Last modified: 2 years ago