list-mail-folder-messages-delta
Get only new, updated, or deleted messages in a mail folder to efficiently synchronize local message stores.
Instructions
Get a set of messages added, deleted, or updated in a specified folder. A delta function call for messages in a folder is similar to a GET request, except that by appropriately applying state tokens in one or more of these calls, you can query for incremental changes in the messages in that folder. It allows you to maintain and synchronize a local store of a user's messages without having to fetch the entire set of messages from the server every time.
💡 TIP: Incremental sync of messages within a mail folder. Graph only supports delta scoped to a folder — use mailFolder-id = 'inbox' for the well-known inbox, or another folder id from list-mail-folders. First call returns all messages plus @odata.deltaLink; subsequent calls with that link return only changes (created/updated/deleted). @odata.nextLink paginates within a single delta window. Deltas expire after ~30 days of inactivity — start over if the server returns 410. Prefer this over full re-list for polling.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| changeType | No | A custom query option to filter the delta response based on the type of change. Supported values are created, updated or deleted. | |
| top | No | Page size (Graph $top). Start small (e.g. 5–15) so responses fit the model context; raise only if needed. Use $select to return fewer fields per item. For more rows, use @odata.nextLink from the response instead of a very large $top. | |
| skip | No | Items to skip for pagination. Not supported with $search. | |
| search | No | KQL search query — wrap value in double quotes. Cannot combine with $filter. | |
| filter | No | OData filter expression. Add $count=true for advanced filters (flag/flagStatus, contains()). Cannot combine with $search. | |
| count | No | Set true to enable advanced query mode (ConsistencyLevel: eventual). Required for complex $filter on flag/flagStatus or contains(). | |
| select | No | Comma-separated fields to return, e.g. id,subject,from,receivedDateTime | |
| orderby | No | Sort expression, e.g. receivedDateTime desc | |
| expand | No | Expand related entities | |
| mailFolderId | Yes | Path parameter: mailFolderId | |
| fetchAllPages | No | Follow @odata.nextLink and merge up to 100 pages into one response. Can return enormous payloads—only when the user explicitly needs a full export. Prefer a small $top first, then paginate or narrow with $filter/$search. | |
| includeHeaders | No | Include response headers (including ETag) in the response metadata | |
| excludeResponse | No | Exclude the full response body and only return success or failure indication |