Configuration

Colporteur reads its config from ~/.config/colporteur/config.toml.

Full example

output_dir = "/var/lib/colporteur/feeds"
max_entries = 50

[accounts.mxroute]
server = "mail.mxroute.com"
username = "news@domain.com"
password = "secret"
mailbox = "INBOX"

[accounts.gmail]
server = "imap.gmail.com"
username = "user@gmail.com"
password = "secret"

[feeds.ideabrowser]
title = "Ideabrowser Daily"
account = "mxroute"
senders = ["notifications@mail.ideabrowser.com"]

[feeds.mixed]
title = "Health & Parenting"
account = "gmail"
senders = ["noreply@health.com", "tips@parenting.com"]
max_entries = 10

Global settings

Key	Type	Default	Description
output_dir	string	required	Directory where Atom XML feed files are written
max_entries	integer	50	Maximum entries kept per feed (oldest trimmed first)
base_url	string	optional	Base URL for serving feeds; used to generate <link rel="alternate"> entries. Must be http:// or https://, no ? or #. Trailing slash is trimmed

Account settings

Defined under [accounts.<name>].

Key	Type	Default	Description
server	string	required	IMAP server hostname
username	string	required	IMAP username
password	string	required	IMAP password or !command (see Passwords)
mailbox	string	"INBOX"	IMAP mailbox to search

Feed settings

Defined under [feeds.<name>]. The <name> becomes the output filename (<name>.xml).

Key	Type	Default	Description
title	string	required	Title of the Atom feed
account	string	required	Key of the account to use (must match an [accounts.<name>])
senders	string[]	required	Email addresses to search for in the mailbox
max_entries	integer	global max_entries	Per-feed override for max entries
url	string	optional	URL added as <link rel="alternate"> on each entry; overrides base_url. Must be http:// or https://

Entry links

RSS readers like Read You expect a <link> element on entries for “read mode”. Colporteur generates entry links in this priority order:

1. Per-feed url (if set)
2. {base_url}/{feed_key}.xml (if base_url is set)
3. No link (if neither is configured)

Set base_url globally and optionally override with per-feed url:

base_url = "https://feeds.example.com"

[feeds.newsletter]
url = "https://newsletter.author.com/archive"

Passwords

Passwords can be specified in three ways:

Syntax	Meaning
password = "secret"	Plain text
password = "!pass show email/imap"	Command — executes via sh -c, uses trimmed stdout
password = "!!starts-with-bang"	Escaped — literal password starting with !

Command examples:

password = "!pass show email/imap"
password = "!gopass show -o email/imap"
password = "!op read 'op://Vault/IMAP/password'"
password = "!secret-tool lookup service imap user newsletters"

Command execution details:

• Runs via sh -c <command> with stdin closed
• Trimmed stdout is used as the password
• Fails with a clear error if the command exits non-zero or produces empty output
• stderr is logged at debug level only
• Unix-only — on Windows, command-based passwords are not supported; use a plain text value instead

Since the config file may contain secrets, ensure it is only readable by the owner:

chmod 600 ~/.config/colporteur/config.toml

On Unix-like systems, colporteur init sets this permission automatically. On other platforms, you may need to adjust file permissions or ACLs manually to restrict access.

State

Colporteur persists sync state at ~/.local/share/colporteur/state.json. This tracks:

• UIDVALIDITY per account — detects mailbox resets
• Last seen UID per sender — enables incremental fetching

If UIDVALIDITY changes (mailbox was rebuilt), the state for that account is reset and all emails are re-fetched.

Validation

Config is validated on load. Colporteur exits with code 3 if:

• output_dir is empty
• No accounts are defined
• No feeds are defined
• A feed references a non-existent account