1IMAPPROC(1) User Commands IMAPPROC(1)
2
6 imapproc - filter emails in remote IMAP folders
7
9 imapproc -H <host> -u <user> --password <password> [options]
10 imapproc -H <host> -u <user> --password-command <cmd> [options]
11
13 imapproc continuously monitors one or more remote IMAP folders and pro‐
14 cesses mail in them according to user defined Python code in an rc
15 file, a user defined piece of Python code. It also logs its actions to
16 a log file. When there is no more mail to process, imaproc sleeps one
17 second and then checks again. And so on. To make imapproc exit after
18 the first filtering run, pass the --once option.
19 imapproc keeps a list of folders in the IMAP account to process. At
21 least least one IMAP folder must be specified for imapproc to run.
22 Folder paths are always absolute. There are two ways to specify this
23 information: by passing command line options, or by setting attributes
24 on the processor object in the rc file. The rc file has priority over
25 the command line options.
26 The typical folder to run imapproc on is INBOX but you can of course
28 specify multiple folders to process.
29 The default location of the rc file for imapproc is ~/.mailprocess‐
31 ing/imap.rc and the default location of its log file is ~/.mailprocess‐
32 ing/log-imap.
33 imapproc can optionally reload the rc file whenever a modification is
35 detected (that is, the file's mtime has changed). This automatic
36 reloading is turned off by default and can be enabled either by passing
37 the --auto-reload-rcfile command line option or by setting the au‐
38 to_reload_rcfile property to True on the processor object in the rc
39 file.
40 imapproc writes its process ID to ~/.mailprocessing/imapproc.pid and
42 uses that PID file for locking as well. If you want to run multiple
43 imapproc instances in parallel, use the --pidfile and --logfile options
44 to give each process a different PID and log file.
45
47 Common options
48 maildirproc and imapproc both take the following common command line
49 options:
50 --version
52 show program's version number and exit
53 -h, --help
55 show this help message and exit
56 --auto-reload-rcfile
58 turn on automatic reloading of the rc file when it has been mod‐
59 ified
60 --dry-run
62 just log what should have been done; implies --once
63 -l FILE, --logfile=FILE
65 send log to FILE instead of the default (~/.maildirproc/log-imap
66 for imapproc and ~/.maildirproc/log-maildir for maildirproc).
67 If you are running multiple maildirproc or imapproc instances,
68 you must specify a dedicated log file for each of these.
69 --log-level=INTEGER
71 only include log messages with this log level or lower; defaults
72 to 1
73 --once only process the maildirs once and then exit; without this flag,
75 maildirproc will scan the maildirs continuously
76 -r FILE, --rcfile=FILE
78 use the given rc file instead of the default (~/.maildirproc/de‐
79 fault.rc)
80 --test test mode; implies --dry-run, --once, --logfile=- and --verbose
82 -v, --verbose
84 increase log level one step
85 imapproc specific options
87 -C, --cache-headers
88 Whether to cache the email headers retrieved from the IMAP serv‐
89 er. By default caching is disabled.
90 --cache-file FILE
92 Store the email header cache in FILE if caching is enabled. If
93 this is not specified explicitly, ~/.maildirproc/HOST.cache will
94 be used, where HOST is the IMAP server's host name passed set
95 with the --host option.
96 -c CERT, --certfile
98 Use SSL certificate file CERT to verify IMAP server's SSL cer‐
99 tificate (only relevant for IMAPS)
100 -H HOST, --host
102 Connect to IMAP server HOST. This option is mandatory
103 -i INTERVAL, --interval
105 Scan IMAP folders for new email every INTERVAL seconds; defaults
106 to 300; will be ignored if --once is specified as well
107 --flag-batchsize SIZE
109 Batch size to use when fetching message flags. Defaults to 200.
110 When there are more messages to fetch flags for, multiple FETCH
111 commands will be issued, each with SIZE or fewer messages. Re‐
112 duce this value if you experience session expiry during message
113 flag retrieval.
114 --header-batchsize SIZE
116 Batch size to use when fetching message headers. Defaults to
117 200. When there are more messages to fetch headers for, multi‐
118 ple FETCH commands will be issued, each with SIZE or fewer mes‐
119 sages. Reduce this value if you experience session expiry dur‐
120 ing message header retrieval.
121 --folder-prefix PREFIX
123 Prefix folder names with the string PREFIX. This is relevant
124 for some IMAP servers that store all folders as subfolders of
125 INBOX. imapproc will attempt to detect this situation, but this
126 detection may not work with all server side IMAP implementa‐
127 tions. If this is the case for your IMAP server, use this op‐
128 tion to specify a prefix explicitly.
129 --folder-separator SEP
131 Use SEP as a separator for folder hierarchies. By default,
132 imapproc will determine the folder separator from the server's
133 LIST response. This should work fine for most IMAP servers.
134 -p PW, --interval
136 Use password PW to authenticate against IMAP server; since this
137 will show up in the process list, this is mainly intended for
138 debugging. Use --password-command otherwise. Either this op‐
139 tion or --password-command is mandatory.
140 --pidfile FILE
142 Write the imapproc process' PID to FILE rather than the default
143 location ~/.imapproc/imapproc.pid. This file is also used for
144 locking so if you need to run multiple different imapproc pro‐
145 cesses in parallel you need to specify different PID and log
146 files for these.
147 --password-command CMD
149 Run command CMD and send use its output as the password to au‐
150 thenticate against the IMAP server with. This is the recommend‐
151 ed approach for specifying the IMAP password. Either this op‐
152 tion or --password is mandatory.
153 -P PORT --port
155 IMAP port to use. Defaults to 143 if --use-ssl is not specified
156 and 993 if it is.
157 -s --use-ssl
159 Use SSL to connect to the IMAP server (default: no).
160 -U USER --user
162 Log in to the IMAP server with user name USER. This option is
163 mandatory.
164 --insecure
166 Do no certificate validation when connecting to an SSL IMAP
167 server (default: no). This means the certificate subject names
168 will be ignored, as will any certificate authorities. Your con‐
169 nection will not be protected from active attackers.
170
172 For some examples, see the examples directory.
173
175 Both SIGINT and SIGTERM will cause imapproc to shut down cleanly, i.e.
176 it will close the IMAP connection and write the current in-memory cache
177 to disk upon receiving either of these signals.
178 SIGHUP will cause imapproc to close and re-open its log file. This can
180 be used for online log rotation in continuous mode.
181
183 maildirproc(1), mailprocessing(5)
184User Commands IMAPPROC(1)