.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Email::Filter 3pm" .TH Email::Filter 3pm "2022-06-03" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Email::Filter \- Library for creating easy email filters .SH "VERSION" .IX Header "VERSION" version 1.035 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 11 \& use Email::Filter; \& my $mail = Email::Filter\->new(emergency => "~/emergency_mbox"); \& $mail\->pipe("listgate", "p5p") if $mail\->from =~ /perl5\-porters/; \& $mail\->accept("perl") if $mail\->from =~ /perl/; \& $mail\->reject("We do not accept spam") if $mail\->subject =~ /enlarge/; \& $mail\->ignore if $mail\->subject =~ /boring/i; \& ... \& $mail\->exit(0); \& $mail\->accept("~/Mail/Archive/backup"); \& $mail\->exit(1); \& $mail\->accept() .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module replaces \f(CW\*(C`procmail\*(C'\fR or \f(CW\*(C`Mail::Audit\*(C'\fR, and allows you to write programs describing how your mail should be filtered. .SH "PERL VERSION" .IX Header "PERL VERSION" This code is effectively abandonware. Although releases will sometimes be made to update contact info or to fix packaging flaws, bug reports will mostly be ignored. Feature requests are even more likely to be ignored. (If someone takes up maintenance of this code, they will presumably remove this notice.) This means that whatever version of perl is currently required is unlikely to change \*(-- but also that it might change at any new maintainer's whim. .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" .Vb 2 \& Email::Filter\->new(); # Read from STDIN \& Email::Filter\->new(data => $string); # Read from string \& \& Email::Filter\->new(emergency => "~simon/urgh"); \& # Deliver here in case of error .Ve .PP This takes an email either from standard input, the usual case when called as a mail filter, or from a string. .PP You may also provide an \*(L"emergency\*(R" option, which is a filename to deliver the mail to if it couldn't, for some reason, be handled properly. .IP "Hint" 3 .IX Item "Hint" If you put your constructor in a \f(CW\*(C`BEGIN\*(C'\fR block, like so: .Sp .Vb 2 \& use Email::Filter; \& BEGIN { $item = Email::Filter\->new(emergency => "~simon/urgh"); } .Ve .Sp right at the top of your mail filter script, you'll even be protected from losing mail even in the case of syntax errors in your script. How neat is that? .PP This method provides the \f(CW\*(C`new\*(C'\fR trigger, called once an object is instantiated. .SS "exit" .IX Subsection "exit" .Vb 1 \& $mail\->exit(1|0); .Ve .PP Sets or clears the 'exit' flag which determines whether or not the following methods exit after successful completion. .PP The sense-inverted 'noexit' method is also provided for backwards compatibility with \f(CW\*(C`Mail::Audit\*(C'\fR, but setting \*(L"noexit\*(R" to \*(L"yes\*(R" got a bit mind-bending after a while. .SS "simple" .IX Subsection "simple" .Vb 1 \& $mail\->simple(); .Ve .PP Gets and sets the underlying \f(CW\*(C`Email::Simple\*(C'\fR object for this filter; see Email::Simple for more details. .SS "header" .IX Subsection "header" .Vb 1 \& $mail\->header("X\-Something") .Ve .PP Returns the specified mail headers. In scalar context, returns the first such header; in list context, returns them all. .SS "body" .IX Subsection "body" .Vb 1 \& $mail\->body() .Ve .PP Returns the body text of the email .SS "from" .IX Subsection "from" .SS "to" .IX Subsection "to" .SS "cc" .IX Subsection "cc" .SS "bcc" .IX Subsection "bcc" .SS "subject" .IX Subsection "subject" .SS "received" .IX Subsection "received" .Vb 1 \& $mail\->
() .Ve .PP Convenience accessors for \f(CW\*(C`header($header)\*(C'\fR .SS "ignore" .IX Subsection "ignore" Ignores this mail, exiting unconditionally unless \f(CW\*(C`exit\*(C'\fR has been set to false. .PP This method provides the \*(L"ignore\*(R" trigger. .SS "accept" .IX Subsection "accept" .Vb 2 \& $mail\->accept(); \& $mail\->accept(@where); .Ve .PP Accepts the mail into a given mailbox or mailboxes. Unix \f(CW\*(C`~/\*(C'\fR and \f(CW\*(C`~user/\*(C'\fR prefices are resolved. If no mailbox is given, the default is determined according to Email::LocalDelivery: \&\f(CW$ENV{MAIL}\fR, \fI/var/spool/mail/you\fR, \fI/var/mail/you\fR, or \&\fI~you/Maildir/\fR. .PP This provides the \f(CW\*(C`before_accept\*(C'\fR and \f(CW\*(C`after_accept\*(C'\fR triggers, and exits unless \f(CW\*(C`exit\*(C'\fR has been set to false. They are passed a reference to the \&\f(CW@where\fR array. .SS "reject" .IX Subsection "reject" .Vb 1 \& $mail\->reject("Go away!"); .Ve .PP This rejects the email; if called in a pipe from a mail transport agent, (such as in a \fI~/.forward\fR file) the mail will be bounced back to the sender as undeliverable. If a reason is given, this will be included in the bounce. .PP This calls the \f(CW\*(C`reject\*(C'\fR trigger. \f(CW\*(C`exit\*(C'\fR has no effect here. .SS "pipe" .IX Subsection "pipe" .Vb 1 \& $mail\->pipe(qw[sendmail foo\e@bar.com]); .Ve .PP Pipes the mail to an external program, returning the standard output from that program if \f(CW\*(C`exit\*(C'\fR has been set to false. The program and each of its arguments must be supplied in a list. This allows you to do things like: .PP .Vb 3 \& $mail\->exit(0); \& $mail\->simple(Email::Simple\->new($mail\->pipe("spamassassin"))); \& $mail\->exit(1); .Ve .PP in the absence of decent \f(CW\*(C`Mail::SpamAssassin\*(C'\fR support. .PP If the program returns a non-zero exit code, the behaviour is dependent on the status of the \f(CW\*(C`exit\*(C'\fR flag. If this flag is set to true (the default), then \f(CW\*(C`Email::Filter\*(C'\fR tries to recover. (See \*(L"\s-1ERROR RECOVERY\*(R"\s0) If not, nothing is returned. .PP If the last argument to \f(CW\*(C`pipe\*(C'\fR is a reference to a hash, it is taken to contain parameters to modify how \f(CW\*(C`pipe\*(C'\fR itself behaves. The only useful parameter at this time is: .PP .Vb 1 \& header_only \- only pipe the header, not the body .Ve .SH "TRIGGERS" .IX Header "TRIGGERS" Users of \f(CW\*(C`Mail::Audit\*(C'\fR will note that this class is much leaner than the one it replaces. For instance, it has no logging; the concept of \&\*(L"local options\*(R" has gone away, and so on. This is a deliberate design decision to make the class as simple and maintainable as possible. .PP To make up for this, however, \f(CW\*(C`Email::Filter\*(C'\fR contains a trigger mechanism provided by Class::Trigger, to allow you to add your own functionality. You do this by calling the \f(CW\*(C`add_trigger\*(C'\fR method: .PP .Vb 1 \& Email::Filter\->add_trigger( after_accept => \e&log_accept ); .Ve .PP Hopefully this will also help subclassers. .PP The methods below will list which triggers they provide. .SH "ERROR RECOVERY" .IX Header "ERROR RECOVERY" If something bad happens during the \f(CW\*(C`accept\*(C'\fR or \f(CW\*(C`pipe\*(C'\fR method, or the \f(CW\*(C`Email::Filter\*(C'\fR object gets destroyed without being properly handled, then a fail-safe error recovery process is called. This first checks for the existence of the \f(CW\*(C`emergency\*(C'\fR setting, and tries to deliver to that mailbox. If there is no emergency mailbox or that delivery failed, then the program will either exit with a temporary failure error code, queuing the mail for redelivery later, or produce a warning to standard error, depending on the status of the \f(CW\*(C`exit\*(C'\fR setting. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Simon Cozens .IP "\(bu" 4 Casey West .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Ricardo Signes .IP "\(bu" 4 William Yardley .IP "\(bu" 4 Will Norris .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Simon Cozens. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.