NAME

       Email::Received - Parse an email Received: header

SYNOPSIS

         use Email::Received;

         for ($mail->header("Received")) {
           my $data = parse_received($_);
           return "SPAM" if rbl_lookup($data->{ip});
         }

DESCRIPTION

       This module is a Perl Email Project rewrite of SpamAssassin's email header parser. We did
       this so that the great work they did in analysing pretty much every possible Received
       header format could be used in applications other than SpamAssassin itself.

       The module provides one function, "parse_received", which takes a single Received line. It
       then produces either nothing, if the line is unparsable, a hash reference like this:

           { reason => "gateway noise" }

       if the line should be ignored for some good reason, and one like this:

          { ip => '64.12.136.4', id => '875522', by => 'xxx.com',
            helo => 'imo-m01.mx.aol.com' }

       if it parsed the message. Possible keys are:

           ip rdns helo ident envfrom auth by id

RULE FORMAT

       Where SpamAssassin used a big static subroutine full of regular expressions to parse the
       data, we build up a big subroutine full of regular expressions dynamically from a set of
       rules. The rules are stored at the bottom of this module. The basic format for a rule
       looks like this:

           ((var=~)?/REGEXP/)? [ACTION; ]+

       The "ACTION" is either "SET variable = $value", "IGNORE "reason"?", "UNPARSABLE" or
       "DONE".

       One control structure is provided, which is basically an "if" statement:

           GIVEN (NOT)? /REGEXP/ {
               ACTION+
           }

   EXPORT
       parse_received

SEE ALSO

       Mail::SpamAssassin::Message::Metadata::Received, from which the rules and some of the IP
       address matching constants were blatantly stolen. Thanks, guys, for doing such a
       comprehensive job!

AUTHOR

       simon, <simon@>

COPYRIGHT AND LICENSE

       Copyright (C) 2006 by simon

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of
       Perl 5 you may have available.