---
title: "fetch messages · RUAL Documentation"
description: "Downloads messages by UID and parses each into the same object mail parse produces : addresses, subject, text, html, attachments, headers. Does not mark…"
canonical: https://docs.rual.nl/block-types/imap/imapconnection_fetch
language: en
---

[Cluster](https://docs.rual.nl/cluster)

[Blocks](https://docs.rual.nl/block-types)

[Interfaces](https://docs.rual.nl/interfaces)

[Blueprints](https://docs.rual.nl/blueprints)

[Blueprint Language](https://docs.rual.nl/engine)

[Tutorials](https://docs.rual.nl/tutorials)

[Home automation](https://docs.rual.nl/home-automation)

[Examples](https://docs.rual.nl/examples)

[Reference](https://docs.rual.nl/reference)

[Architecture](https://docs.rual.nl/architecture)

[Troubleshooting](https://docs.rual.nl/troubleshooting)

Other

# fetch messages

This block is part of the [`imap`](https://docs.rual.nl/block-types/imap) group and was last modified in core [`v15.0.1`](https://docs.rual.nl/core-versions/150001).

Downloads messages by UID and parses each into the same object `mail parse` produces : addresses, subject, text, html, attachments, headers. Does not mark them read unless `mark seen` is on.

- flow `flow`

- connection required `imapconnection`

- mailbox `value` Mailbox the uids belong to. Defaults to `INBOX`.

Default `INBOX`

- uids `array` UIDs to fetch : wire `imap search`'s uids here. At most 500 per fetch.

- uid `number` A single UID, for the one-message case. Added to `uids` when both are filled.

- mark seen `condition` Mark the fetched messages read. Off by default: reading leaves the mailbox as it was.

Default `false`

- headers only `condition` Fetch the headers and skip bodies and attachments.

Default `false`

- include attachment content `condition` On (the default) attachments carry `content_base64`. Off gives name, type and size only.

Default `true`

- max attachment bytes `number` Per-part ceiling on decoded attachment content. A larger part keeps its metadata and is reported with `truncated: true`.

Default `26214400`

- include raw `condition` Also output the raw RFC 822 message per entry, for `imap append` or archiving.

Default `false`

- max message bytes `number` A message larger than this is not downloaded: it is listed with `skipped` set and no `message`. Ceiling 50 MB; one fetch pulls at most 100 MB in total.

Default `26214400`

- flow `flow`

- connection `imapconnection`

- success `condition`

- error `value`

- messages `array`

- first message `object`

- count `number`

Fetches the given uids from mailbox (default INBOX) and outputs messages: [{ uid, flags[], seen, answered, flagged, deleted, draft, internal_date (epoch ms), size, message, parse_error, raw? }] plus count, and message = the first entry for the single-uid case. message is the mail_parse object: { from {name,email}, to[], cc[], reply_to[], subject, date, message_id, in_reply_to, references[], text, html, attachments[{name,content_type,size,content_base64,inline,cid}], headers, size, spam_score, authentication }. A message the parser cannot read is still listed with message=null and parse_error set, so a flow that moves or deletes what it handled never skips a uid. A uid the mailbox no longer holds is simply absent. mark_seen=false (default) uses BODY.PEEK and leaves unread state untouched : a flow polling 'unseen' must set it, or mark the uids with imap set flags, or it will see the same messages every run. headers_only=true fetches the header block only (no bodies, no attachments). include_content=false drops attachment bytes. include_raw=true adds the raw RFC 822 text. Bounds: at most 500 uids per fetch, a message over max_message_bytes (default 25 MB, ceiling 50 MB) is never downloaded, and one fetch pulls at most 100 MB in total; a message refused by either bound is STILL listed, with skipped set and message null, so a flow can move or delete it by uid without reading it : never silently omitted. headers_only fetches are exempt from the byte bounds. Suppressed in a simulation.

| `read emails` |
| --- |
| `download messages` |
| `imap fetch` |
| `get mail` |

A typical wiring for [fetch messages](https://docs.rual.nl/block-types/imap/imapconnection_fetch): a [function trigger](https://docs.rual.nl/block-types/globals/trigger_custom_function) starts the flow; [move messages](https://docs.rual.nl/block-types/imap/imapconnection_move) feeds the `connection` pin; the `flow` out pin feeds [debug](https://docs.rual.nl/block-types/state%2520ui/state_debug).

[![Studio canvas example for the fetch messages block: typical wiring for fetch messages.](https://docs.rual.nl/canvas-examples/imapconnection_fetch.png)](https://docs.rual.nl/canvas-examples/imapconnection_fetch.png?v=3)

## Version history

Introduced in [`v15.0.1`](https://docs.rual.nl/core-versions/150001).

- [Back to `imap`](https://docs.rual.nl/block-types/imap): Return to the main group to view all sub-groups

- [Back to `imap`](https://docs.rual.nl/block-types/imap?group=imap): Return to the group to view all blocks within this group

Was this page helpful? [Tell us what to improve](https://docs.rual.nl/support) · RUAL Docs is an integral component of the [RUAL ecosystem](https://rual.nl)