NAME

       Sisimai - Mail Analyzing Interface for bounce mails.

SYNOPSIS

           use Sisimai;

DESCRIPTION

       "Sisimai" is a Mail Analyzing Interface for email bounce, is a Perl module to parse
       RFC5322 bounce mails and generating structured data as JSON from parsed results. "Sisimai"
       is a coined word: Sisi (the number 4 is pronounced "Si" in Japanese) and MAI (acronym of
       "Mail Analyzing Interface").

BASIC USAGE

   "make('/path/to/mbox')"
       "make" method provides feature for getting parsed data from bounced email messages like
       following.

           use Sisimai;
           my $v = Sisimai->make('/path/to/mbox'); # or Path to Maildir/
           #  $v = Sisimai->make(\'From Mailer-Daemon ...');

           if( defined $v ) {
               for my $e ( @$v ) {
                   print ref $e;                   # Sisimai::Data
                   print ref $e->recipient;        # Sisimai::Address
                   print ref $e->timestamp;        # Sisimai::Time

                   print $e->addresser->address;   # shironeko@example.org # From
                   print $e->recipient->address;   # kijitora@example.jp   # To
                   print $e->recipient->host;      # example.jp
                   print $e->deliverystatus;       # 5.1.1
                   print $e->replycode;            # 550
                   print $e->reason;               # userunknown
                   print $e->origin;               # /var/spool/bounce/2022-2222.eml

                   my $h = $e->damn;               # Convert to HASH reference
                   my $j = $e->dump('json');       # Convert to JSON string
                   my $y = $e->dump('yaml');       # Convert to YAML string
               }

               # Dump entire list as a JSON
               use JSON '-convert_blessed_universally';
               my $json = JSON->new->allow_blessed->convert_blessed;

               printf "%s\n", $json->encode($v);
           }

       If you want to get bounce records which reason is "delivered", set "delivered" option to
       make() method like the following:

           my $v = Sisimai->make('/path/to/mbox', 'delivered' => 1);

   "dump('/path/to/mbox')"
       "dump" method provides feature to get parsed data from bounced email as JSON.

           use Sisimai;
           my $v = Sisimai->dump('/path/to/mbox'); # or Path to Maildir
           print $v;                               # JSON string

OTHER WAYS TO PARSE

   Read email data from STDIN
       If you want to pass email data from STDIN, specify STDIN at the first argument of dump()
       and make() method like following command:

           % cat ./path/to/bounce.eml | perl -MSisimai -lE 'print Sisimai->dump(STDIN)'

   Callback Feature
       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

OTHER METHODS

   "engine()"
       "engine" method provides table including parser engine list and it's description.

           use Sisimai;
           my $v = Sisimai->engine();
           for my $e ( keys %$v ) {
               print $e;           # Sisimai::MTA::Sendmail
               print $v->{ $e };   # V8Sendmail: /usr/sbin/sendmail
           }

   "reason()"
       "reason" method provides table including all the reasons Sisimai can detect

           use Sisimai;
           my $v = Sisimai->reason();
           for my $e ( keys %$v ) {
               print $e;           # Blocked
               print $v->{ $e };   # 'Email rejected due to client IP address or a hostname'
           }

   "match()"
       "match" method receives an error message as a string and returns a reason name like the
       following:

           use Sisimai;
           my $v = '550 5.1.1 User unknown';
           my $r = Sisimai->match($v);
           print $r;   # "userunknown"

   "version()"
       "version" method returns the version number of Sisimai.

           use Sisimai;
           print Sisimai->version; # 4.25.0p5

SEE ALSO

       Sisimai::Mail - Mailbox or Maildir object
       Sisimai::Data - Parsed data object
       <https://libsisimai.org/> - Sisimai X A successor to bounceHammer, Library to parse error
       mails
       <https://tools.ietf.org/html/rfc3463> - RFC3463: Enhanced Mail System Status Codes
       <https://tools.ietf.org/html/rfc3464> - RFC3464: An Extensible Message Format for Delivery
       Status Notifications
       <https://tools.ietf.org/html/rfc5321> - RFC5321: Simple Mail Transfer Protocol
       <https://tools.ietf.org/html/rfc5322> - RFC5322: Internet Message Format

REPOSITORY

       <https://github.com/sisimai/p5-sisimai> - Sisimai on GitHub

WEB SITE

       <https://libsisimai.org/> - A successor to bounceHammer, Library to parse error mails.

       <https://github.com/sisimai/rb-sisimai> - Ruby version of Sisimai

AUTHOR

       azumakuniyuki

COPYRIGHT

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

LICENSE

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