new

    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

This takes an email either from standard input, the usual case when called as a mail filter, or from a string.

You may also provide an "emergency" option, which is a filename to deliver the mail to if it couldn't, for some reason, be handled properly.

Hint

If you put your constructor in a "BEGIN" block, like so:

    use Email::Filter;
    BEGIN { $item = Email::Filter->new(emergency => "~simon/urgh"); }
    

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?

This method provides the "new" trigger, called once an object is instantiated.

exit

    $mail->exit(1|0);

Sets or clears the 'exit' flag which determines whether or not the following methods exit after successful completion.

The sense-inverted 'noexit' method is also provided for backwards compatibility with "Mail::Audit", but setting "noexit" to "yes" got a bit mind-bending after a while.

simple

    $mail->simple();

Gets and sets the underlying "Email::Simple" object for this filter; see Email::Simple for more details.

header

    $mail->header("X-Something")

Returns the specified mail headers. In scalar context, returns the first such header; in list context, returns them all.

body

    $mail->body()

Returns the body text of the email

from

to

cc

bcc

subject

received

    $mail-><header>()

Convenience accessors for "header($header)"

ignore

This method provides the "ignore" trigger.

accept

    $mail->accept();
    $mail->accept(@where);

Accepts the mail into a given mailbox or mailboxes. Unix "~/" and "~user/" prefices are resolved. If no mailbox is given, the default is determined according to Email::LocalDelivery: $ENV{MAIL}, /var/spool/mail/you, /var/mail/you, or ~you/Maildir/.

This provides the "before_accept" and "after_accept" triggers, and exits unless "exit" has been set to false. They are passed a reference to the @where array.

reject

    $mail->reject("Go away!");

This rejects the email; if called in a pipe from a mail transport agent, (such as in a ~/.forward file) the mail will be bounced back to the sender as undeliverable. If a reason is given, this will be included in the bounce.

This calls the "reject" trigger. "exit" has no effect here.

pipe

    $mail->pipe(qw[sendmail foo\@bar.com]);

Pipes the mail to an external program, returning the standard output from that program if "exit" 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:

    $mail->exit(0);
    $mail->simple(Email::Simple->new($mail->pipe("spamassassin")));
    $mail->exit(1);

in the absence of decent "Mail::SpamAssassin" support.

If the program returns a non-zero exit code, the behaviour is dependent on the status of the "exit" flag. If this flag is set to true (the default), then "Email::Filter" tries to recover. (See "ERROR RECOVERY") If not, nothing is returned.

If the last argument to "pipe" is a reference to a hash, it is taken to contain parameters to modify how "pipe" itself behaves. The only useful parameter at this time is:

  header_only - only pipe the header, not the body