Module fetch 

Fetching new mail, read-only, into the account’s Maildir.

The first sync brings the last days of each folder (sync_days, 14 by default), so the Porch shows soon. Then what arrives, by UID, the inbox first, and, a round at a time, everything older, newest first: all your mail is kept here, and the history setting only chooses what the window shows. Older mail never takes the disk’s reserve (disk::room): it waits, and the window says so. Where sync stopped is kept per account and folder in $XDG_STATE_HOME/sioul/sync/<id>.toml, after every batch, so an interrupted sync resumes where it stopped.

watch keeps the inbox open with IDLE (RFC 2177), so a code reaches you within seconds of reaching your provider.

Structs

Arrived 🔒

A message as the server gave it, before Sioul checks and stores it.

Control

How a watcher is told to stop, or to fetch now instead of waiting, and at what pace.

Deadline 🔒

The end of a wait, on both clocks: the wall clock counts a phone’s sleep, the monotonic clock keeps a wall clock put back from stretching it.

FolderState 🔒

Parked 🔒

A watcher parked after a lasting error: it waits for a nudge (a new password, “Sync now”, the app back) instead of ending, then tries again; a refused password, unchanged, not before REFUSED_AGAIN, unless asked to (Control::retry).

Reach 🔒

How far back a folder was fetched: since a day (Unix seconds), or everything.

Report

What one sync brought.

SyncState 🔒

Where sync stopped, per folder.

Enums

Kept

How much of a folder is kept here: all of it, all of it since a day (Unix seconds), or nothing known (never fetched, left on the server, or fetched before Sioul kept how far back). A search asks the server for the rest.

Constants

BATCH 🔒

Messages per FETCH: small enough to save progress often.

FETCH 🔒

FIRST_PAUSE 🔒

The first wait before reconnecting; it doubles up to ten minutes.

IDLE 🔒

IDLE is renewed this often: RFC 2177 asks for less than 29 minutes, and a connection that died silently is noticed sooner.

INBOX 🔒

LONGEST_PAUSE 🔒

LOOK 🔒

How often a long wait looks at the wall clock: the monotonic clock, which timers count, stops while a phone sleeps.

OLDER_PER_ROUND 🔒

Older messages fetched per round, so new mail never waits long behind them.

POLL 🔒

Without IDLE, Sioul looks this often.

REALTIME 🔒

Real time: every folder fetched this often, for a code or a password you wait for.

REFUSED_AGAIN 🔒

A refused password is tried again, unchanged, this long after at the soonest, however often the watcher is nudged: retries can lock an account.

SLOW 🔒

Paces longer than this keep no connection open between fetches: IDLE would bring the inbox sooner than wished (RFC 2177 renews under 29 minutes).

Functions

backfill 🔒

The older messages of a folder, those not here yet, a round at a time, newest first, each round sized first so the disk keeps its reserve; the folder remembers once it holds everything.

block_on 🔒

fetch_batch 🔒

One FETCH: every message of set. BODY.PEEK leaves the \Seen flag alone.

fetch_folder 🔒

Fetches a folder’s new messages into its Maildir, then (full) brings back what changed there on the server and older mail. One fetch at a time per account, across processes too (the window and sioul sync): otherwise both would see the same new UIDs and write each message twice.

fetch_new 🔒

Fetches the inbox’s new messages into the Maildir.

first_window 🔒

The first day a first sync brings: the first window (sync_days); older mail follows, a round at a time.

forget_folder_state 🔒

Where a folder’s sync stopped, forgotten: the next sync of it starts over.

imap_date 🔒

A day as IMAP writes dates: “18-Sep-2026”, with English month names whatever your language (RFC 9051 §9, date-month).

inbox

The inbox’s arrivals alone, in one connection and without IDLE: what a phone’s background service fetches at its rhythm, while Sioul is closed (crates/sioul-app/src/steps.rs). One fetch at a time per account, across processes too, as for every fetch (fetch_folder).

keep_open 🔒

One connection, kept as long as it lives: fetch, wait for news, fetch again.

kept

How much of folder (its server name) this device holds, as its last sync left it.

local_uids 🔒

The UIDs of a folder’s messages kept here, for this UIDVALIDITY.

lock 🔒

An exclusive lock on a file, released when the returned file is dropped.

maildir_flags 🔒

IMAP’s system flags as Maildir’s letters (https://cr.yp.to/proto/maildir.html), and the keywords kept, $Junk and $NotJunk, as Dovecot’s lowercase letters (maildir::KEYWORDS): what you or a mail client said of a message, which the spam filter learns from and the Porch heeds. reconcile keeps them in step.

other_folders 🔒

Lists the folders, keeps the list, and fetches every folder but the inbox; returns the files written, and whether older mail waits for room.

runtime 🔒

sizes_of 🔒

The sizes of messages on the server (RFC822.SIZE), by UID, before fetching them.

store_checked 🔒

Checks each message (SPF, DKIM, DMARC…, see verify) and writes it into the Maildir.

sync

Fetches what is new since the last sync, in every folder; the first time, the last sync_days days. The report is the inbox’s.

test

Logs in and opens the inbox read-only: the number of messages in it.

to_fetch 🔒

The UIDs to fetch of those found, oldest first, and the newest of those here already (else last_uid). Here already: a sync stopped between storing mail and saving where it stopped, or whose state was lost, finds them again, and they are not stored twice.

wait 🔒

Waits length, or less when stopped or nudged; on the wall clock too (see Deadline). Whether it was nudged.

watch

Keeps the inbox open and fetches what arrives, until stopped (see Control). Every sync is reported, even an empty one, and every error, before trying again; after a lasting one (a refused login, see SyncError::is_lasting) it waits for a nudge, then tries again with the password kept then (see Parked).

woken 🔒

Returns when the watcher is stopped or nudged.