1Mail::Procmail(3) User Contributed Perl Documentation Mail::Procmail(3)
2
6 Mail::Procmail - Procmail-like facility for creating easy mail filters.
7
9 use Mail::Procmail;
10 # Set up. Log everything up to log level 3.
12 my $m_obj = pm_init ( loglevel => 3 );
13 # Pre-fetch some interesting headers.
15 my $m_from = pm_gethdr("from");
16 my $m_to = pm_gethdr("to");
17 my $m_subject = pm_gethdr("subject");
18 # Default mailbox.
20 my $default = "/var/spool/mail/".getpwuid($>);
21 pm_log(1, "Mail from $m_from");
23 pm_ignore("Non-ASCII in subject")
25 if $m_subject =~ /[\232-\355]{3}/;
26 pm_resend("jojan")
28 if $m_to =~ /jjk@/i;
29 # Make sure I see these.
31 pm_deliver($default, continue => 1)
32 if $m_subject =~ /getopt(ions|(-|::)?long)/i;
33 # And so on ...
35 # Final delivery.
37 pm_deliver($default);
38
40 procmail is a great mail filter program, but it has weird recipe
41 format. It's pattern matching capabilities are basic and often
42 insufficient. I wanted something flexible whereby I could filter my
43 mail using the power of Perl.
44 I've been considering to write a procmail replacement in Perl for a
46 while, but it was Simon Cozen's "Mail::Audit" module, and his article
47 in The Perl Journal #18, that set it off.
48 I first started using Simon's great module, and then decided to write
50 my own since I liked certain things to be done differently. And I
51 couldn't wait for his updates.
52 "Mail::Procmail" allows a piece of email to be logged, examined,
54 delivered into a mailbox, filtered, resent elsewhere, rejected, and so
55 on. It is designed to allow you to easily create filter programs to
56 stick in a .forward or .procmailrc file, or similar.
57
59 Note that several changes are due to personal preferences and do not
60 necessarily imply deficiencies in "Mail::Audit".
61 General
63 Not object oriented. Procmail functionality typically involves one
64 single message. All (relevant) functions are exported.
65 Delivery
67 Each of the delivery methods is able to continue (except pm_reject
68 and pm_ignore).
69 Each of the delivery methods is able to pretend they did it (for
71 testing a new filter).
72 No default file argument for mailbox delivery, since this is system
74 dependent.
75 Each of the delivery methods logs the line number in the calling
77 program so one can deduce which 'rule' caused the delivery.
78 Message IDs can be checked to suppress duplicate messages.
80 System commands can be executed for their side-effects.
82 pm_ignore logs a reason as well.
84 pm_reject will fake a "No such user" status to the mail transfer
86 agent.
87 Logging
89 The logger function is exported as well. Logging is possible to a
90 named file, STDOUT or STDERR.
91 Since several deliveries can take place in parallel, logging is
93 protected against concurrent access, and a timestamp/pid is
94 included in log messages.
95 A log reporting tool is included.
97 Robustness
99 Exit with TEMPFAIL instead of die in case of problems.
100 pm_pipe_to ignores SIGPIPE.
102 pm_pipe_to returns the command exit status if continuation is
104 selected.
105 Commands and pipes can be protected against concurrent access
107 using lockfiles.
108
110 Note that most delivery routines exit the program unless the attribute
111 "continue=>1" is passed.
112 Also, the delivery routines log the line number in the calling program
114 so it is easy to find out which 'rule' caused a specific delivery to
115 take place.
116 pm_init
118 This routine performs the basic initialisation. It must be called once.
119 Example:
121 pm_init (logfile => "my.log", loglevel => 3, test => 1);
123 Attributes:
125 • fh
127 An open file handle to read the message from. Defaults to STDIN.
129 • logfile
131 The name of a file to log messages to. Each message will have a
133 timestamp attached.
134 The attribute may be 'STDOUT' or 'STDERR' to achieve logging to
136 standard output or error respectively.
137 • loglevel
139 The amount of information that will be logged.
141 • test
143 If true, no actual delivery will be done. Suitable to test a new
145 setup. Note that file locks are done, so lockfiles may be created
146 and deleted.
147 • debug
149 Provide some debugging info.
151 • trace
153 Provide some tracing info, eventually.
155 • verbose
157 Produce verbose information, eventually.
159 pm_gethdr
161 This routine fetches the contents of a header. The result will have
162 excess whitepace tidied up.
163 The header is reported using warn() if the debug attribute was passed
165 (with a true value) to pm_init();
166 Example:
168 $m_rcvd = pm_gethdr("received"); # get first (or only) Received: header
170 $m_rcvd = pm_gethdr("received",2); # get 3rd Received: header
171 @m_rcvd = pm_gethdr("received"); # get all Received: headers
172 pm_gethdr_raw
174 Like pm_gethdr, but without whitespace cleanup.
175 pm_body
177 This routine fetches the body of a message, as a reference to an array
178 of lines.
179 Example:
181 $body = pm_body(); # ref of lines
183 $body = join("", @{pm_body()}); # as one string
184 pm_deliver
186 This routine performs delivery to a Unix style mbox file, or maildir.
187 In case of an mbox file, the file is locked first by acquiring
189 exclusive access. Note that older style locking, with a lockfile with
190 ".lock" extension, is not supported.
191 Example:
193 pm_deliver("/var/spool/mail/".getpwuid($>));
195 Attributes:
197 • continue
199 If true, processing will continue after delivery. Otherwise the
201 program will exit with a DELIVERED status.
202 pm_pipe_to
204 This routine performs delivery to a command via a pipe.
205 Return the command exit status if the continue attribute is supplied.
207 If execution is skipped due to test mode, the return value will be 0.
208 See also attribute "testalso" below.
209 If the name of a lockfile is supplied, multiple deliveries are
211 throttled.
212 Example:
214 pm_pipe_to("my_filter", lockfile => "/tmp/pm.lock");
216 Attributes:
218 • lockfile
220 The name of a file that is used to guard against multiple
222 deliveries. The program will try to exclusively create this file
223 before proceding. Upon completion, the lock file will be removed.
224 • continue
226 If true, processing will continue after delivery. Otherwise the
228 program will exit with a DELIVERED status, even when the command
229 failed.
230 • testalso
232 Do this, even in test mode.
234 pm_command
236 Executes a system command for its side effects.
237 If the name of a lockfile is supplied, multiple executes are throttled.
239 This would be required if the command manipulates external data in an
240 otherwise unprotected manner.
241 Example:
243 pm_command("grep foo some.dat > /tmp/pm.dat",
245 lockfile => "/tmp/pm.dat.lock");
246 Attributes:
248 • lockfile
250 The name of a file that is used to guard against multiple
252 executions. The program will try to exclusively create this file
253 before proceding. Upon completion, the lock file will be removed.
254 testalso
256 Do this, even in test mode.
258 pm_resend
260 Send this message through to some other user.
261 Example:
263 pm_resend("root");
265 Attributes:
267 • continue
269 If true, processing will continue after delivery. Otherwise the
271 program will exit with a DELIVERED status.
272 pm_reject
274 Reject a message. The sender will get a mail back with the reason for
275 the rejection (unless stderr has been redirected).
276 Example:
278 pm_reject("Non-existent address");
280 pm_ignore
282 Ignore a message. The program will do nothing and just exit with a
283 DELIVERED status. A descriptive text may be passed to log the reason
284 for ignoring.
285 Example:
287 pm_ignore("Another make money fast message");
289 pm_dupcheck
291 Check for duplicate messages. Reject the message if its message ID has
292 already been received.
293 Example:
295 pm_dupcheck(scalar(pm_gethdr("message-id")));
297 Attributes:
299 • dbm
301 The name of a DBM file (created if necessary) to store the message
303 IDs. The default name is ".msgids" in the HOME directory.
304 • retain
306 The amount of time, in days, that subsequent identical message IDs
308 are considered duplicates. Each new occurrence will refresh the
309 time stamp. The default value is 14 days.
310 • continue
312 If true, the routine will return true or false depending on the
314 message ID being duplicate. Otherwise, if it was duplicate, the
315 program will exit with a DELIVERED status.
316 Warning: In the current implementation, the DBM file will grow
318 unlimited. A separate tool will be supplied to expire old message IDs.
319 pm_lockfile
321 The program will try to get an exclusive lock using this file.
322 Example:
324 $lock_id = pm_lockfile("my.mailbox.lock");
326 The lock id is returned, or undef on failure.
328 pm_unlockfile
330 Unlocks a lock acquired earlier using pm_lockfile().
331 Example:
333 pm_unlockfile($lock_id);
335 If unlocking succeeds, the lock file is removed.
337 pm_log
339 Logging facility. If pm_init() was supplied the name of a log file,
340 this file will be opened, created if necessary. Every log message
341 written will get a timestamp attached. The log level (first argument)
342 must be less than or equal to the loglevel attribute used with
343 pm_init(). If not, this message will be skipped.
344 Example:
346 pm_log(2,"Retrying");
348 pm_report
350 pm_report() produces a summary report from log files from
351 Mail::Procmail applications.
352 Example:
354 pm_report(logfile => "pmlog");
356 The report shows the deliveries, and the rules that caused the
358 deliveries. For example:
359 393 393 deliver[203] /home/jv/Mail/perl5-porters.spool
361 370 370 deliver[203] /home/jv/Mail/perl6-language.spool
362 174 174 deliver[203] /home/jv/Mail/perl6-internals.spool
363 160 81 deliver[311] /var/spool/mail/jv
364 46 deliver[337]
365 23 deliver[363]
366 10 deliver[165]
367 The first column is the total number of deliveries for this target.
369 The second column is the number of deliveries triggered by the
370 indicated rule. If more rules apply to a target, this line is followed
371 by additional lines with an empty first and last column.
372 Attributes:
374 • logfile
376 The name of the logfile to process.
378 If no logfile attribute is passed, pm_report() reads all files supplied
380 on the command line. This makes it straighforward to run from the
381 command line:
382 $ perl -MMail::Procmail -e 'pm_report()' syslog/pm_logs/*
384
386 The following lines at the start of .procmailrc will cause a copy of
387 each incoming message to be saved in $HOME/syslog/mail, after which the
388 procmail-pl is run as a TRAP program (see the procmailrc
389 documentation). As a result, procmail will transfer the exit status of
390 procmail-pl to the mail transfer agent that invoked procmail (e.g.,
391 sendmail, or postfix).
392 LOGFILE=$HOME/syslog/procmail
394 VERBOSE=off
395 LOGABSTRACT=off
396 EXITCODE=
397 TRAP=$HOME/bin/procmail-pl
398 :0:
400 $HOME/syslog/mail
401 WARNING: procmail seems to have problems when $HOME/syslog/mail gets
403 too big (over 50Mb). If you want to maintain a huge archive, you can
404 specify excess extents, like this:
405 :0:
407 $HOME/syslog/mail-ext1
408 :0:
410 $HOME/syslog/mail-ext2
411
413 An extensive example can be found in the examples directory of the
414 "Mail::Procmail" kit.
415
417 Mail::Internet
418 LockFile::Simple
420 procmail documentation.
422
424 Johan Vromans, Squirrel Consultancy <jvromans@squirrel.nl>
425 Some parts are shamelessly stolen from Mail::Audit by Simon Cozens
427 <simon@cpan.org>, who admitted that he stole most of it from programs
428 by Tom Christiansen.
429
431 This program is Copyright 2000,2004 by Squirrel Consultancy. All rights
432 reserved.
433 This program is free software; you can redistribute it and/or modify it
435 under the terms of either: a) the GNU General Public License as
436 published by the Free Software Foundation; either version 1, or (at
437 your option) any later version, or b) the "Artistic License" which
438 comes with Perl.
439 This program is distributed in the hope that it will be useful, but
441 WITHOUT ANY WARRANTY; without even the implied warranty of
442 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU
443 General Public License or the Artistic License for more details.
444perl v5.38.0 2023-07-20 Mail::Procmail(3)