NAME
    Mail::Bounce - analyze error message.

SYNOPSIS
        use Mail::Message;
        my $msg = Mail::Message->parse( { fd => \*STDIN } );

        use Mail::Bounce;
        my $bouncer = new Mail::Bounce;
        $bouncer->analyze( $msg );

        # show results
        for my $a ( $bouncer->address_list ) {
            print "address: $a\n";

            print " status: ";
            print $bouncer->status( $a );
            print "\n";

            print " reason: ";
            print $bouncer->reason( $a );
            print "\n";
            print "\n";
        }

DESCRIPTION
    try to analyze the given error message, which is a Mail::Message object.

    For non DSN pattern, try to analyze it by using modules in
    "Mail::Bounce::" which can recognize MTA specific and domain specific
    patterns.

    For example,

      Mail::Bounce

                    $msg
                  --------> Mail::Bounce::DSN::analyze()
                  <--------
                   $result

    returned $result provides the following information:

        $result = {
            address1 => {
                Original-Recipient => 'rfc822; addr',
                Final-Recipient    => 'rfc822; addr',
                Diagnostic-Code    => 'reason ...',
                Action             => 'failed',
                Status             => '4.0.0',
                Reporting-MTA      => 'dns; server.fml.org',
                Received-From-MTA  => 'DNS; server.fml.org',
                hints              => ... which module matches ...,
            },

            address2 => {
                ... snip ...
            },

            ...
        };

METHODS
  new()
    constructor.

  analyze($msg)
    $msg is a "Mail::Message" object. This routine is a top level switch
    which provides the entrance for "Mail::Bounce::" modules, for example,
    "Mail::Bounce::DSN".

    "Mail::Bounce::$model::analyze( \$msg, \$result )" method in each module
    is the actual model specific analyzer. $result has an answer of analyze
    if the error message pattern is one of already known formats.

  address_list()
    return ARRAY of addresses found in the error message.

  status($addr)
    return status (string) for $addr. The status can be extracted from
    "result" analyze() method gives.

  reason($addr)
    return error reason (string) for $addr. It can be extracted from
    "result" analyze() method gives.

  look_like_japanese(string)
    return 1 if "string" looks Japanese one in JIS/SJIS/EUC code. return 0
    unless.

  address_cleanup(hint, addr)
    clean up "addr" and return it.

    "hint" gives a special hint for some specific MTA or domain. It is
    rarely used.

SECURITY CONSIDERATION
    The address returned by Mail::Bounce class may be unsafe. Please
    validate it by some other class such as FML::Restriction class before
    use it at some other place.

CODING STYLE
    See "http://www.fml.org/software/FNF/" on fml coding style guide.

AUTHOR
    Ken'ichi Fukamachi

COPYRIGHT
    Copyright (C) 2001,2002,2003,2004,2005 Ken'ichi Fukamachi

    All rights reserved. This program is free software; you can redistribute
    it and/or modify it under the same terms as Perl itself.

HISTORY
    Mail::Bounce first appeared in fml8 mailing list driver package. See
    "http://www.fml.org/" for more details.