R2E(1)

📦 version 3.14, in nixpkgs unstable

💅 R2E(1) 💅

okay so bestie, welcome to the General Commands Manual glow-up of R2E(1) — yes, it's section 1, it's a command, and it's about to be your new personality. 🫶

✨ NAME ✨

r2e — receive RSS feeds by email 💌

🦋 SYNOPSIS 🦋

r2e [options] <command> [<args>]

🌸 DESCRIPTION 🌸

r2e is a simple little program you can run in your crontab(5). It keeps an eye on RSS feeds for you and then sends you a nicely formatted email message for each new item. no cap, that's the whole vibe. 👑

Wanna do a quick start? Here's the lowkey iconic three-step:

r2e new your@yourdomain.com
r2e add feedname http://feed.url/somewhere.rss
r2e run

That last one — r2e run — is the one you're eventually gonna want to drop into your crontab if you want stuff getting sent to you automatically, without you having to lift a finger. 💅

⭐ OPTIONS ⭐

  • -h, --help — prints the rss2email help and then dips. ✌️
  • -v, --version — prints the rss2email version and exits.
  • --full-version — prints the versions of Python, the compiler that was used to compile Python, and the packages used by rss2email. the whole receipts, basically. 🧾
  • -c, --config <path> — the program configuration is read from $XDG_CONFIG_HOME/rss2mail.cfg by default (see also FILES and ENVIRONMENT VARIABLES below). use this option to point it at a different configuration file.
  • -d, --data <path> — dynamic program data is read from $XDG_DATA_HOME/rss2mail.json by default (see also FILES and ENVIRONMENT VARIABLES below). use this option to point it at a different data file.
  • -V, --verbose — cranks the logging verbosity up a notch. 🔊

👑 COMMANDS 👑

  • new [<email>] — creates a brand new feed database. If the <email> argument is given, it sets the default email address that mails get sent to. 🎀
  • email [<email>] — updates the default target email address to <email>.
  • add [--only-new] <name> <url> [<email>] — subscribes to a feed. The <name> argument gives the feed a name so you can mess with it later. <url> is the URL of the feed. The optional <email> argument is the email address to send new items to, which overrides the default address for this particular feed only. Repeat this for each feed you want to subscribe to. 🔁

The --only-new option fetches the feed at addition time without sending the entries, which makes subsequent run execution consider them as already having been sent. It should be used when you're only interested in entries that are not yet in the feed at the time of running add.

  • run [--no-send] [--clean] [<index> [<index> ...]] — scans the feeds and sends emails for new items. This is the one you can run in a cron job. ⏰

The --no-send option stops r2e from sending any email. This can be useful the first time you run it, because otherwise it would send an email for every single available feed entry and that's a lot of emails bestie. 😭

The --clean option reduces the database size by removing old entries. It forces a download of selected feeds or all feeds, and should only be used weekly or monthly. don't be extra about it. 🙈

If an <index> is specified, r2e will only download that feed. <index> can be either the feed name (as set by add) or the feed index (as shown by list).

  • list — lists all the feeds in the database. the receipts, the roster, the whole cast. 📋
  • pause [<index> [<index> ...]] — pauses feeds (aka disables fetching). The <index> option selects the feed(s) to pause (see run for possible values). If no <index> is given, all feeds are paused. shhh, nap time. 😴
  • unpause [<index> [<index> ...]] — unpauses feeds (aka enables fetching). wakey wakey. ☀️
  • delete <index> [<index> [<index> ...]] — removes a feed (or feeds) from the database. The <index> option selects the feed(s) to delete (see run for possible values). 💀
  • reset [<index> [<index> ...]] — forgets dynamic feed data (e.g. so it'll re-send old entries). The <index> option selects the feed(s) to reset (see run for possible values). If no <index> is given, all feeds are reset. selective memory loss, iconic. 🧠
  • opmlimport [<path>] — imports new feeds from OPML. <path> is the file from which the OPML data will be read. If <path> is not given, r2e reads the data from stdin.
  • opmlexport [<path>] — exports all feeds to OPML. <path> is the file to which the OPML data will be written. If <path> is not given, r2e writes the data to stdout.

💖 CONFIGURATION 💖

The program's behavior can be controlled via the $XDG_CONFIG_HOME/rss2email.cfg (see also FILES and ENVIRONMENT VARIABLES below). The file format is similar to a Microsoft Windows INI file. It is parsed by Python's ConfigParser class, so go peek at the Python documentation at http://docs.python.org/3/library/configparser.html if you want the format details. 🐍

The config file stores general configuration (applied to all feeds) in the [DEFAULT] section. The new command will create a configuration file for you, which you can edit as you see fit. The add command will add feed-specific sections. To override any a setting for all feeds, change the value in the [DEFAULT] section. To override a setting for a particular feed, add that setting to the feed-specific section. Here's an example overriding use-publisher-email and name-format for the feedname feed. 👇

[DEFAULT]
from = user@rss2email.invalid
force-from = False
use-publisher-email = False
name-format = {feed-title}: {author}
  ...
verbose = warning

[feed.feedname]
url = http://feed.url/somewhere.rss
use-publisher-email = True
name-format = {author} ({feed.title})

You can configure the following items: ✨

📬 Addressing

  • from — the email address messages are from by default.
  • use-8bit — Transfer-Encoding. For local mailing it is safe and convenient to use 8bit.
  • force-from — True: only use the 'from' address. False: use the email address specified by the feed, when possible.
  • use-publisher-email — True: use the publisher's email if you can't find the author's. False: just use the 'from' email instead.
  • name-format — if empty, only use the feed email address rather than friendly name plus email address. Available attributes may include 'feed', 'feed-name', 'feed-url', 'feed-title', 'author', and 'publisher', but only 'feed', 'feed-name', and 'feed-url' are guaranteed. 👀
  • to — set this to default To email addresses.

🌐 Fetching

⚙️ Processing

  • active — True: fetch, process, and email feeds. False: don't fetch, process, or email feeds.
  • digest — True: send a single, multi-entry email per feed per rss2email run. False: send a single email per entry.
  • digest-type — message content-type for digests. Valid values are 'multipart/digest' and 'multipart/mixed'. The former is the default, but many mail user agents do not support it. ⚠️
  • date-header — True: generate Date header based on item's date, when possible. False: generate Date header based on time sent.
  • date-header-order — a comma-delimited list of some combination of ('issued', 'created', 'modified', 'expired') expressing ordered list of preference in dates to use for the Date header of the email.
  • bonus-header — set this to add bonus headers to all emails. Example: bonus-header = 'Approved: joe@bob.org'
  • trust-guid — True: receive one email per post. False: receive an email every time a post changes.
  • trust-link — True: receive one email per unique link url. False: defer to trust-guid preference. Toggling this for existing feeds may result in duplicates, because the old entries will not be recorded under their new link-based ids. 🫠
  • encodings — to most correctly encode emails with international characters, we iterate through the list below and use the first character set that works.
  • post-process — user processing hooks. Note the space after the module name. Example: post-process = 'rss2email.post_process.downcase downcase_message'
  • digest-post-process — user processing hooks for digest messages. If 'digest' is enabled, the usual 'post-process' hook gets to message the per-entry messages, but this hook is called with the full digest message before it is mailed. Example: digest-post-process = 'rss2email.post_process.downcase downcase_message'
  • subject-format — the format for the Subject line. Available attributes are 'feed', 'feed-name', 'feed-url', 'feed-title'.

🎨 HTML conversion

  • html-mail — True: send text/html messages when possible. False: convert HTML to plain text.
  • use-css — use CSS.
  • css — optional CSS styling.

🧚 html2text options

  • unicode-snob — use Unicode characters instead of their ascii psuedo-replacements.
  • links-after-each-paragraph — put the links after each paragraph instead of at the end.
  • inline-links — use inline, rather than reference, formatting for images and links.
  • wrap-links — wrap links according to body width.
  • body-width — wrap long lines at position. Any negative value for no wrapping, 0 for 78 width (compatibility), or any positive width.

📮 Mailing

  • email-protocol — select protocol from: sendmail, smtp, imap, maildir
  • sendmail — path to sendmail (or compatible).

📧 SMTP configuration

  • smtp-auth — set to True to use SMTP AUTH
  • smtp-username — username for SMTP AUTH
  • smtp-password — password for SMTP AUTH
  • smtp-server — SMTP server
  • smtp-ssl — connect to the SMTP server using SSL

📥 IMAP configuration

  • imap-auth — set to True to use IMAP auth.
  • imap-username — username for IMAP authentication
  • imap-password — password for IMAP authentication
  • imap-server — IMAP server
  • imap-port — IMAP port
  • imap-ssl — connect to the IMAP server using SSL
  • imap-mailbox — where we should store new messages

📁 Maildir configuration

  • maildir-path — path of maildir to write messages into
  • maildir-mailbox — mailbox within maildir-path to write messages into

🌈 Miscellaneous

  • user-agent — string to use as HTTP User-Agent in web requests and as the User-Agent header in outgoing emails. If present, __VERSION__ and __URL__ are replaced with rss2email version number and webpage.
  • verbose — verbosity (one of 'error', 'warning', 'info', or 'debug').

🗂️ FILES 🗂️

  • $XDG_CONFIG_HOME/rss2email.cfg — if this file exists, it is read to configure the program.
  • $XDG_DATA_HOME/rss2email.json — the database of feeds. Use r2e to add, remove, or modify feeds, do not edit it directly. 🚫

🌸 ENVIRONMENT VARIABLES 🌸

okay bestie so all the env vars r2e cares about come straight out of the XDG Base Directory Specification, which is basically the collective agreement to stop dumping everyone's config and data files in random places and standardize where user-specific stuff lives. iconic behaviour tbh 🫶

  • XDG_CONFIG_HOME — the dir where your config files wanna live. Defaults to $HOME/.config. 💅
  • XDG_DATA_HOME — the dir where your data files wanna live. Defaults to $HOME/.local/share. ✨
  • XDG_RUNTIME_DIR — the dir where lockfiles go. Defaults to /tmp/rss2email-UID. 🔒
  • XDG_CONFIG_DIRS — a colon ':' separated, preference-ordered list of base dirs for config files, on top of whatever $XDG_CONFIG_HOME is doing. Defaults to /etc/xdg. And listen — if multiple config files get found along this path, the ConfigParser class reads all of them, no cap (see also CONFIGURATION above, bestie, it's all connected 🦋).
  • XDG_DATA_DIRS — a colon ':' separated, preference-ordered list of base dirs for data files. Defaults to /usr/local/share/:/usr/share/. And here's the plot twist: only the first matching file is used. not all of them. just the first. the rest are simply not the main character 😭

👑 AUTHORS 👑

rss2email was started by Aaron Swartz — yeah, that Aaron Swartz, absolute legend, we stan forever 🕊️💜 — and it's currently maintained by a whole group of people doing the lord's work.

for the full, more complete list of contributors, go peek at the AUTHORS file in the rss2email distribution. everyone in there ate, fr fr. 🎀

🐛 REPORTING BUGS 🐛

found a bug? don't suffer in silence bestie, that's not the vibe. report it by creating an issue at:

https://github.com/rss2email/rss2email

go forth and open that issue, you're doing amazing sweetie 🫶💖

and that's a wrap on the whole page!! 🌈 this was R2E(1) — the version that lives in your manual and the date it got stamped in there, both chilling right down in the footer where footers belong. go forth, feed your RSS, and remember: you're the main character of your own inbox. periodt. 💅✨🦋

📦 where this page comes from