> ## 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.

> ## Agent Instructions
> Charter works for any HTTP API, including the user's own. The packs are examples of the result, not the limit: an API with no pack is declared the same way, following https://raw.githubusercontent.com/r28ai/charter/main/docs/.mintlify/skills/declaring-charter-tools/SKILL.md.
> Charter is for agents that act in customers' accounts: every call is checked field by field before it's sent, the app says whose account each call is for, and the same declarations list what each tool can reach. https://docs.r28.ai/charter/llms.txt says what it is and lists every page.

# messages_list

> List or search messages, across the mailbox or in one folder (an ID, or a well-known name such as inbox or sentitems). Filter with OData, or search with KQL. Bodies are left out; bodyPreview has the first 255 characters.

GET`https://graph.microsoft.com/v1.0/me/mailFolders/{folderId}/messages`GET`https://graph.microsoft.com/v1.0/me/messages`

The operation is served at each of these routes. A call goes to the first one whose path parameters it gives, so leaving an optional one out is how the wider route is chosen.

```python outlook_messages_list.py theme={null}
import asyncio

from charter.packs import outlook

result = asyncio.run(outlook.messages_list.ainvoke({}))
```

> [!NOTE]
>
> Requires `https://graph.microsoft.com/Mail.Read` or `https://graph.microsoft.com/Mail.ReadWrite`. Pages by cursor: `next_link` is sent back as `next_link`.

## Path parameters

| Field | Type | Description |
| - | - | - |
| `folderId` | `string` | The folder ID, or a well-known folder name. Well-known names work regardless of the locale of the user's mailbox: archive, clutter, conflicts, conversationhistory, deleteditems, drafts, inbox, junkemail, localfailures, msgfolderroot, outbox, recoverableitemsdeletions, scheduled, searchfolders, sentitems, serverfailures, syncissues. Omit it to get the messages in the whole mailbox, including the Deleted Items and Clutter folders. |

## Query parameters

| Field | Type | Description |
| - | - | - |
| `$top` | `integer` | Use the $top query parameter to specify the number of items to be included in the result. The default page size is 10 messages. Use `$top\` to customize the page size, within the range of 1 and 1000. ≥ 1; ≤ 1000 |
| `$filter` | `string` | Use the $filter query parameter to get just a subset of a collection. When using `$filter`and`$orderby` in the same query to get messages: properties that appear in `$orderby`must also appear in`$filter`; properties that appear in `$orderby`are in the same order as in`$filter`; and properties that are present in `$orderby`appear in`\$filter`before any properties that aren't. OData syntax, strings in single quotes with any inside doubled:`isRead eq false`, `from/emailAddress/address eq '[ada@example.com](mailto:ada@example.com)'`. One conversation is `conversationId eq '\<conversationId>'\`. |
| `$orderby` | `string` | Use the \$orderby query parameter to specify the sort order of the items returned from Microsoft Graph. The default order is ascending. To sort results in ascending or descending order, append either `asc` or `desc` to the field name, separated by a space; for example, `receivedDateTime desc`. |
| `$search` | `string` | When you search messages without specifying message properties, the search targets these default properties: from, subject, and body. Alternatively, you can search messages by specifying message property names that Keyword Query Language (KQL) syntax recognizes: attachment, bcc, body, cc, from, hasAttachment, importance, kind, participants, received, recipients, sent, size, subject, to. Search results are sorted by the date and time the message was sent. A `$search` request returns up to 1,000 results. Wrap the whole query in double quotes, as Graph requires: "pizza" or "from:ada subject:invoice". matches `^".*"$` |
| `$select` | `string` | Use the $select query parameter to return a subset of properties for a resource. With $select, you can specify a subset or a superset of the default properties. For example, `from,subject` returns only the from and subject properties. A list leaves each message's full body out. Select `uniqueBody` to get each one's own text — what it adds to the thread, without the quoted history. |
| `$expand` | `string` | Use the \$expand query string parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results. |
| `$count` | `boolean` | Use \$count=true to include a count of the total number of items in a collection alongside the page of data values returned from Microsoft Graph. |
| `nextLink` | `string` | The `next_link` the previous page of this same call returned (Graph's `@odata.nextLink`), to fetch the page after it. The link carries every parameter of the first request, the folder included, so when it is set the others are ignored. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.