1R2E(1) General Commands Manual R2E(1)
2
6 r2e - receive RSS feeds by email
7
9 r2e [options] <command> [<args>]
10
12 r2e is a simple program which you can run in your crontab(5). It
13 watches RSS feeds and sends you nicely formatted email message for each
14 new item.
15 For a quick start with r2e try these steps:
17 r2e new your@yourdomain.com
19 r2e add feedname http://feed.url/somewhere.rss
20 r2e run
21 The last command should eventually be put into your crontab if you want
24 things be sent you automatically.
25
27 -h, --help
28 Print the rss2email help and exit.
29 -v, --version
31 Print the rss2email version and exit.
32 --full-version
34 Print the versions of Python, the compiler used to compile Python,
35 and packages used by rss2email.
36 -c, --config <path>
38 The program configuration is read from $XDG_CON‐
39 FIG_HOME/rss2mail.cfg by default (see also FILES and ENVIRONMENT
40 VARIABLES below). Use this option to set a different configuration
41 file.
42 -d, --data <path>
44 Dynamic program data is read from $XDG_DATA_HOME/rss2mail.json by
45 default (see also FILES and ENVIRONMENT VARIABLES below). Use this
46 option to set a different data file.
47 -V, --verbose
49 Increment the logging verbosity.
50
52 new [<email>]
53 Create a new feed database. If the <email> argument is given, it
54 sets the default email address that mails are sent to.
55 email [<email>]
57 Update the default target email address to <email>.
58 add [--only-new] <name> <url> [<email>]
60 Subscribe to a feed. The <name> argument gives the feed a name for
61 future manipulation. <url> is the URL of the feed. The optional
62 <email> argument is the email address to send new items to, over‐
63 riding the default address for this particular feed. Repeat for
64 each feed you want to subscribe to.
65 The --only-new option fetches the feed at addition time without
67 sending the entries, making subsequent run execution consider them
68 as already having been sent. It should be used when one is only in‐
69 terested in entries that are not yet in the feed at the time of
70 running add.
71 run [--no-send] [--clean] [<index> [<index> ...]]
73 Scan the feeds and send emails for new items. This can be run in
74 a cron job.
75 The --no-send option stops r2e from sending any email. This can be
77 useful the first time you run it, as otherwise it would send an
78 email for every available feed entry.
79 The --clean option reduces the database size by removing old en‐
81 tries. It forces a download of selected feeds or all feeds, and
82 should only be used weekly or monthly.
83 If an <index> is specified, r2e will only download that feed. <in‐
85 dex> can be either the feed name (as set by add) or the feed index
86 (as shown by list).
87 list List all the feeds in the database.
89 pause [<index> [<index> ...]]
91 Pause feeds (disable fetching). The <index> option selects the
92 feed(s) to pause (see run for possible values). If no <index>
93 is given, all feeds are paused.
94 unpause [<index> [<index> ...]]
96 Unpause feeds (enable fetching).
97 delete <index> [<index> [<index> ...]]
99 Remove a feed (or feeds) from the database. The <index> option
100 selects the feed(s) to delete (see run for possible values).
101 reset [<index> [<index> ...]]
103 Forget dynamic feed data (e.g. to re-send old entries). The
104 <index> option selects the feed(s) to reset (see run for possi‐
105 ble values). If no <index> is given, all feeds are reset.
106 opmlimport [<path>]
108 Import new feeds from OPML. <path> is the file from which the
109 OPML data will be read. If <path> is not given r2e reads the
110 data from stdin.
111 opmlexport [<path>]
113 Export all feeds to OPML. <path> is the file to which the OPML
114 data will be written. If <path> is not given r2e writes the
115 data to stdout.
116
118 The program's behavior can be controlled via the $XDG_CON‐
119 FIG_HOME/rss2email.cfg (see also FILES and ENVIRONMENT VARIABLES be‐
120 low). The file format is similar to a Microsoft Windows INI file. It
121 is parsed by Python's ConfigParser class, so see the Python documenta‐
122 tion at http://docs.python.org/3/library/configparser.html for format
123 details.
124 The config file stores general configuration (applied to all feeds) in
126 the [DEFAULT] section. The new command will create a configuration
127 file for you, which you can edit as you see fit. The add command will
128 add feed-specific sections. To override any a setting for all feeds,
129 change the value in the [DEFAULT] section. To override a setting for a
130 particular feed, add that setting to the feed-specific section. Here
131 is an example overriding use-publisher-email and name-format for the
132 feedname feed.
133 [DEFAULT]
135 from = user@rss2email.invalid
136 force-from = False
137 use-publisher-email = False
138 name-format = {feed-title}: {author}
139 ...
140 verbose = warning
141 [feed.feedname]
143 url = http://feed.url/somewhere.rss
144 use-publisher-email = True
145 name-format = {author} ({feed.title})
146 You can configure the following items:
148 Addressing
150 from The email address messages are from by default
151 use-8bit
153 Transfer-Encoding. For local mailing it is safe and convenient
154 to use 8bit.
155 force-from
157 True: Only use the 'from' address. False: Use the email address
158 specified by the feed, when possible.
159 use-publisher-email
161 True: Use the publisher's email if you can't find the author's.
162 False: Just use the 'from' email instead.
163 name-format
165 If empty, only use the feed email address rather than friendly
166 name plus email address. Available attributes may include
167 'feed', 'feed-name', 'feed-url', 'feed-title', 'author', and
168 'publisher', but only 'feed', 'feed-name', and 'feed-url' are
169 guaranteed.
170 to Set this to default To email addresses.
172 Fetching
174 proxy Set an HTTP proxy (e.g. 'http://your.proxy.here:8080/')
175 feed-timeout
177 Set the timeout (in seconds) for feed server response
178 Processing
180 active True: Fetch, process, and email feeds. False: Don't fetch,
181 process, or email feeds
182 digest True: Send a single, multi-entry email per feed per rss2email
184 run. False: Send a single email per entry.
185 digest-type
187 Message content-type for digests. Valid values are 'multi‐
188 part/digest' and 'multipart/mixed'. The former is the default,
189 but many mail user agents do not support it.
190 date-header
192 True: Generate Date header based on item's date, when possible.
193 False: Generate Date header based on time sent.
194 date-header-order
196 A comma-delimited list of some combination of ('issued', 'cre‐
197 ated', 'modified', 'expired') expressing ordered list of prefer‐
198 ence in dates to use for the Date header of the email.
199 bonus-header
201 Set this to add bonus headers to all emails Example: bonus-
202 header = 'Approved: joe@bob.org'
203 trust-guid
205 True: Receive one email per post. False: Receive an email every
206 time a post changes.
207 trust-link
209 True: Receive one email per unique link url. False: Defer to
210 trust-guid preference. Toggling this for existing feeds may re‐
211 sult in duplicates, because the old entries will not be recorded
212 under their new link-based ids.
213 encodings
215 To most correctly encode emails with international characters,
216 we iterate through the list below and use the first character
217 set that works.
218 post-process
220 User processing hooks. Note the space after the module name.
221 Example: post-process = 'rss2email.post_process.downcase down‐
222 case_message'
223 digest-post-process
225 User processing hooks for digest messages. If 'digest' is en‐
226 abled, the usual 'post-process' hook gets to message the per-en‐
227 try messages, but this hook is called with the full digest mes‐
228 sage before it is mailed. Example: digest-post-process =
229 'rss2email.post_process.downcase downcase_message'
230 subject-format
232 The format for the Subject line. Available attributes are
233 'feed', 'feed-name', 'feed-url', 'feed-title'.
234 HTML conversion
236 html-mail
237 True: Send text/html messages when possible. False: Convert
238 HTML to plain text.
239 use-css
241 Use CSS
242 css Optional CSS styling
244 html2text options
246 unicode-snob
247 Use Unicode characters instead of their ascii psuedo-replace‐
248 ments
249 links-after-each-paragraph
251 Put the links after each paragraph instead of at the end.
252 inline-links
254 Use inline, rather than reference, formatting for images and
255 links.
256 wrap-links
258 Wrap links according to body width.
259 body-width
261 Wrap long lines at position. Any negative value for no wrapping,
262 0 for 78 width (compatibility), or any positive width.
263 Mailing
265 email-protocol
266 Select protocol from: sendmail, smtp, imap, maildir
267 sendmail
269 Path to sendmail (or compatible)
270 SMTP configuration
272 smtp-auth
273 Set to True to use SMTP AUTH
274 smtp-username
276 username for SMTP AUTH
277 smtp-password
279 password for SMTP AUTH
280 smtp-server
282 SMTP server
283 smtp-ssl
285 Connect to the SMTP server using SSL
286 IMAP configuration
288 imap-auth
289 set to True to use IMAP auth.
290 imap-username
292 username for IMAP authentication
293 imap-password
295 password for IMAP authentication
296 imap-server
298 IMAP server
299 imap-port
301 IMAP port
302 imap-ssl
304 connect to the IMAP server using SSL
305 imap-mailbox
307 where we should store new messages
308 Maildir configuration
310 maildir-path
311 Path of maildir to write messages into
312 maildir-mailbox
314 Mailbox within maildir-path to write messages into
315 Miscellaneous
317 user-agent
318 String to use as HTTP User-Agent in web requests and as the
319 User-Agent header in outgoing emails. If present, __VERSION__
320 and __URL__ are replaced with rss2email version number and web‐
321 page.
322 verbose
324 Verbosity (one of 'error', 'warning', 'info', or 'debug').
325
327 $XDG_CONFIG_HOME/rss2email.cfg
328 If this file exists, it is read to configure the program.
329 $XDG_DATA_HOME/rss2email.json
331 The database of feeds. Use r2e to add, remove, or modify feeds, do
332 not edit it directly.
333
335 The environment variables used by r2e are all defined in the XDG Base
336 Directory Specification, which aims to standardize locations for user-
337 specific configuration and data files.
338 XDG_CONFIG_HOME
340 The preferred directory for configuration files. Defaults to
341 $HOME/.config.
342 XDG_DATA_HOME
344 The preferred directory for data files. Defaults to $HOME/.lo‐
345 cal/share.
346 XDG_RUNTIME_DIR
348 The preferred directory for lockfiles. Defaults to /tmp/rss2email-
349 UID
350 XDG_CONFIG_DIRS
352 A colon ':' separated, preference ordered list of base directories
353 for configuration files in addition to $XDG_CONFIG_HOME. Defaults
354 to /etc/xdg. If multiple configuration files are found in this
355 path, they will all be read by the ConfigParser class (see also
356 CONFIGURATION above).
357 XDG_DATA_DIRS
359 A colon ':' separated, preference ordered list of base directories
360 for data files. Defaults to /usr/local/share/:/usr/share/. Only
361 the first matching file is used.
362
364 rss2email was started by Aaron Swartz, and is currently maintained by a
365 group of people. For a more complete list of contributors, see the AU‐
366 THORS file in the rss2email distribution.
367
369 Report bugs by creating an issue at
370 ⟨https://github.com/rss2email/rss2email⟩.
371 R2E(1)