1Mail::Procmail(3)     User Contributed Perl Documentation    Mail::Procmail(3)
2
3
4

NAME

6       Mail::Procmail - Procmail-like facility for creating easy mail filters.
7

SYNOPSIS

9           use Mail::Procmail;
10
11           # Set up. Log everything up to log level 3.
12           my $m_obj = pm_init ( loglevel  => 3 );
13
14           # 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
19           # Default mailbox.
20           my $default = "/var/spool/mail/".getpwuid($>);
21
22           pm_log(1, "Mail from $m_from");
23
24           pm_ignore("Non-ASCII in subject")
25             if $m_subject =~ /[\232-\355]{3}/;
26
27           pm_resend("jojan")
28             if $m_to =~ /jjk@/i;
29
30           # Make sure I see these.
31           pm_deliver($default, continue => 1)
32             if $m_subject =~ /getopt(ions|(-|::)?long)/i;
33
34           # And so on ...
35
36           # Final delivery.
37           pm_deliver($default);
38

DESCRIPTION

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
45       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
49       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
53       "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

DIFFERENCES WITH MAIL::AUDIT

59       Note that several changes are due to personal preferences and do not
60       necessarily imply deficiencies in "Mail::Audit".
61
62       General
63           Not object oriented. Procmail functionality typically involves one
64           single message. All (relevant) functions are exported.
65
66       Delivery
67           Each of the delivery methods is able to continue (except pm_reject
68           and pm_ignore).
69
70           Each of the delivery methods is able to pretend they did it (for
71           testing a new filter).
72
73           No default file argument for mailbox delivery, since this is system
74           dependent.
75
76           Each of the delivery methods logs the line number in the calling
77           program so one can deduce which 'rule' caused the delivery.
78
79           Message IDs can be checked to suppress duplicate messages.
80
81           System commands can be executed for their side-effects.
82
83           pm_ignore logs a reason as well.
84
85           pm_reject will fake a "No such user" status to the mail transfer
86           agent.
87
88       Logging
89           The logger function is exported as well. Logging is possible to a
90           named file, STDOUT or STDERR.
91
92           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
96           A log reporting tool is included.
97
98       Robustness
99           Exit with TEMPFAIL instead of die in case of problems.
100
101           pm_pipe_to ignores  SIGPIPE.
102
103           pm_pipe_to returns the command exit status if continuation is
104           selected.
105
106           Commands and pipes can be protected  against concurrent access
107           using lockfiles.
108

EXPORTED ROUTINES

110       Note that most delivery routines exit the program unless the attribute
111       "continue=>1" is passed.
112
113       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
117   pm_init
118       This routine performs the basic initialisation. It must be called once.
119
120       Example:
121
122           pm_init (logfile => "my.log", loglevel => 3, test => 1);
123
124       Attributes:
125
126       •   fh
127
128           An open file handle to read the message from. Defaults to STDIN.
129
130       •   logfile
131
132           The name of a file to log messages to. Each message will have a
133           timestamp attached.
134
135           The attribute may be 'STDOUT' or 'STDERR' to achieve logging to
136           standard output or error respectively.
137
138       •   loglevel
139
140           The amount of information that will be logged.
141
142       •   test
143
144           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
148       •   debug
149
150           Provide some debugging info.
151
152       •   trace
153
154           Provide some tracing info, eventually.
155
156       •   verbose
157
158           Produce verbose information, eventually.
159
160   pm_gethdr
161       This routine fetches the contents of a header. The result will have
162       excess whitepace tidied up.
163
164       The header is reported using warn() if the debug attribute was passed
165       (with a true value) to pm_init();
166
167       Example:
168
169           $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
173   pm_gethdr_raw
174       Like pm_gethdr, but without whitespace cleanup.
175
176   pm_body
177       This routine fetches the body of a message, as a reference to an array
178       of lines.
179
180       Example:
181
182           $body = pm_body();                  # ref of lines
183           $body = join("", @{pm_body()});     # as one string
184
185   pm_deliver
186       This routine performs delivery to a Unix style mbox file, or maildir.
187
188       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
192       Example:
193
194           pm_deliver("/var/spool/mail/".getpwuid($>));
195
196       Attributes:
197
198       •   continue
199
200           If true, processing will continue after delivery. Otherwise the
201           program will exit with a DELIVERED status.
202
203   pm_pipe_to
204       This routine performs delivery to a command via a pipe.
205
206       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
210       If the name of a lockfile is supplied, multiple deliveries are
211       throttled.
212
213       Example:
214
215           pm_pipe_to("my_filter", lockfile => "/tmp/pm.lock");
216
217       Attributes:
218
219       •   lockfile
220
221           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
225       •   continue
226
227           If true, processing will continue after delivery. Otherwise the
228           program will exit with a DELIVERED status, even when the command
229           failed.
230
231       •   testalso
232
233           Do this, even in test mode.
234
235   pm_command
236       Executes a system command for its side effects.
237
238       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
242       Example:
243
244           pm_command("grep foo some.dat > /tmp/pm.dat",
245                      lockfile => "/tmp/pm.dat.lock");
246
247       Attributes:
248
249       •   lockfile
250
251           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
255           testalso
256
257           Do this, even in test mode.
258
259   pm_resend
260       Send this message through to some other user.
261
262       Example:
263
264           pm_resend("root");
265
266       Attributes:
267
268       •   continue
269
270           If true, processing will continue after delivery. Otherwise the
271           program will exit with a DELIVERED status.
272
273   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
277       Example:
278
279           pm_reject("Non-existent address");
280
281   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
286       Example:
287
288           pm_ignore("Another make money fast message");
289
290   pm_dupcheck
291       Check for duplicate messages. Reject the message if its message ID has
292       already been received.
293
294       Example:
295
296           pm_dupcheck(scalar(pm_gethdr("message-id")));
297
298       Attributes:
299
300       •   dbm
301
302           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
305       •   retain
306
307           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
311       •   continue
312
313           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
317       Warning: In the current implementation, the DBM file will grow
318       unlimited. A separate tool will be supplied to expire old message IDs.
319
320   pm_lockfile
321       The program will try to get an exclusive lock using this file.
322
323       Example:
324
325           $lock_id = pm_lockfile("my.mailbox.lock");
326
327       The lock id is returned, or undef on failure.
328
329   pm_unlockfile
330       Unlocks a lock acquired earlier using pm_lockfile().
331
332       Example:
333
334           pm_unlockfile($lock_id);
335
336       If unlocking succeeds, the lock file is removed.
337
338   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
345       Example:
346
347           pm_log(2,"Retrying");
348
349   pm_report
350       pm_report() produces a summary report from log files from
351       Mail::Procmail applications.
352
353       Example:
354
355           pm_report(logfile => "pmlog");
356
357       The report shows the deliveries, and the rules that caused the
358       deliveries. For example:
359
360         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
368       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
373       Attributes:
374
375       •   logfile
376
377           The name of the logfile to process.
378
379       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
383           $ perl -MMail::Procmail -e 'pm_report()' syslog/pm_logs/*
384

USING WITH PROCMAIL

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
393           LOGFILE=$HOME/syslog/procmail
394           VERBOSE=off
395           LOGABSTRACT=off
396           EXITCODE=
397           TRAP=$HOME/bin/procmail-pl
398
399           :0:
400           $HOME/syslog/mail
401
402       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
406           :0:
407           $HOME/syslog/mail-ext1
408
409           :0:
410           $HOME/syslog/mail-ext2
411

EXAMPLE

413       An extensive example can be found in the examples directory of the
414       "Mail::Procmail" kit.
415

SEE ALSO

417       Mail::Internet
418
419       LockFile::Simple
420
421       procmail documentation.
422

AUTHOR

424       Johan Vromans, Squirrel Consultancy <jvromans@squirrel.nl>
425
426       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
434       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
440       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.
444
445
446
447perl v5.38.0                      2023-07-20                 Mail::Procmail(3)
Impressum