> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r28.ai/charter/llms.txt
> Use this file to discover all available pages before exploring further.

# messages_list

> List messages in the user's mailbox.

<div className="tool-route"><span className="tool-row-method" data-method="GET">GET</span><code>{"https://gmail.googleapis.com/gmail/v1/users/{userId}/messages"}</code></div>

```python gmail_messages_list.py theme={null}
from charter.packs import gmail

result = await gmail.messages_list.ainvoke({})
```

<Note>
  Requires `https://www.googleapis.com/auth/gmail.modify`. Pages by cursor: `nextPageToken` is sent back as `pageToken`. Costs 5 against the provider's own quota.
</Note>

## Path parameters

<div className="reference-table">
  | Field    | Type     | Description                                                                                                                                                    |
  | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `userId` | `string` | The user's email address. The special value 'me' can be used to indicate the authenticated user. <span className="field-constraints">defaults to `"me"`</span> |
</div>

## Query parameters

<div className="reference-table">
  | Field              | Type        | Description                                                                                                                                                                                                                                                                                                                                        |
  | ------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `maxResults`       | `integer`   | Maximum number of messages to return. This field defaults to 100. The maximum allowed value for this field is 500. <span className="field-constraints">≥ 1; ≤ 500; defaults to `100`</span>                                                                                                                                                        |
  | `pageToken`        | `string`    | Page token to retrieve a specific page of results in the list.                                                                                                                                                                                                                                                                                     |
  | `q`                | `string`    | Only return messages matching the specified query. Supports the same query format as the Gmail search box. For example, "from:[someuser@example.com](mailto:someuser@example.com) rfc822msgid:\<[somemsgid@example.com](mailto:somemsgid@example.com)> is:unread". Parameter cannot be used when accessing the api using the gmail.metadata scope. |
  | `labelIds`         | `string`\[] | 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.                                                                                                                                                                              |
  | `includeSpamTrash` | `boolean`   | Include messages from SPAM and TRASH in the results.                                                                                                                                                                                                                                                                                               |
</div>