NAME

       Sisimai::Message - Convert bounce email text to data structure.

SYNOPSIS

           use Sisimai::Mail;
           use Sisimai::Message;

           my $mailbox = Sisimai::Mail->new('/var/mail/root');
           while( my $r = $mailbox->read ) {
               my $p = Sisimai::Message->new('data' => $r);
           }

           my $notmail = '/home/neko/Maildir/cur/22222';   # is not a bounce email
           my $mailobj = Sisimai::Mail->new($notmail);
           while( my $r = $mailobj->read ) {
               my $p = Sisimai::Message->new('data' => $r);  # $p is "undef"
           }

DESCRIPTION

       Sisimai::Message convert bounce email text to data structure. It resolve email text into
       an UNIX From line, the header part of the mail, delivery status, and RFC822 header part.
       When the email given as a argument of "new" method is not a bounce email, the method
       returns "undef".

CLASS METHODS

   "new(Hash reference)"
       "new()" is a constructor of Sisimai::Message

           my $mailtxt = 'Entire email text';
           my $message = Sisimai::Message->new('data' => $mailtxt);

       If you have implemented a custom MTA module and use it, set the value of "load" in the
       argument of this method as an array reference like following code:

           my $message = Sisimai::Message->new(
                               'data' => $mailtxt,
                               'load' => ['Your::Custom::MTA::Module']
                         );

       Beginning from v4.19.0, `hook` argument is available to callback user defined method like
       the following codes:

           my $cmethod = sub {
               my $argv = shift;
               my $data = {
                   'queue-id' => '',
                   'x-mailer' => '',
                   'precedence' => '',
               };

               # Header part of the bounced mail
               for my $e ( 'x-mailer', 'precedence' ) {
                   next unless exists $argv->{'headers'}->{ $e };
                   $data->{ $e } = $argv->{'headers'}->{ $e };
               }

               # Message body of the bounced email
               if( $argv->{'message'} =~ /^X-Postfix-Queue-ID:\s*(.+)$/m ) {
                   $data->{'queue-id'} = $1;
               }

               return $data;
           };

           my $message = Sisimai::Message->new(
               'data' => $mailtxt,
               'hook' => $cmethod,
           );
           print $message->catch->{'x-mailer'};    # Apple Mail (2.1283)
           print $message->catch->{'queue-id'};    # 2DAEB222022E
           print $message->catch->{'precedence'};  # bulk

INSTANCE METHODS

   "(from)"
       "from()" returns the UNIX From line of the email.

           print $message->from;

   "header()"
       "header()" returns the header part of the email.

           print $message->header->{'subject'};    # Returned mail: see transcript for details

   "ds()"
       "ds()" returns an array reference which include contents of delivery status.

           for my $e ( @{ $message->ds } ) {
               print $e->{'status'};   # 5.1.1
               print $e->{'recipient'};# neko@example.jp
           }

   "rfc822()"
       "rfc822()" returns a hash reference which include the header part of the original message.

           print $message->rfc822->{'from'};   # cat@example.com
           print $message->rfc822->{'to'};     # neko@example.jp

   "catch()"
       "catch()" returns any data generated by user-defined method passed at the `hook` argument
       of new() constructor.

AUTHOR

       azumakuniyuki

COPYRIGHT

       Copyright (C) 2014-2020 azumakuniyuki, All rights reserved.

LICENSE

       This software is distributed under The BSD 2-Clause License.