view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    * __Sender information__: `addresser`, `senderdomain`, 
    * __Recipient information__: `recipient`, `destination`, `alias`
    * __Delivery information__: `action`, `replycode`, `deliverystatus`, `command`
    * __Bounce details__: `reason`, `diagnosticcode`, `diagnostictype`, `feedbacktype`, `feedbackid`, `hardbounce`
    * __Message details__: `subject`, `messageid`, `listid`,
    * __Evaluation metrics (User-calculated)__: `toxic`, `bogus`, `catch`
    * __Additional information__: `decodedby`, `timezoneoffset`, `lhost`, `rhost`, `token`
  * Output formats
    * Perl (Hash, Array)
    * JSON (by using [`JSON`](https://metacpan.org/pod/JSON) module)
    * YAML ([`YAML`](https://metacpan.org/dist/YAML/view/lib/YAML.pod) module or 
            [`YAML::Syck`](https://metacpan.org/pod/YAML::Syck) module required)
* __Easy to Install, Use.__
  * `cpan`, `cpanm`, or `cpm`
  * `git clone & make`
* __High Precision of Analysis__
  * Support [61 MTAs/MDAs/ESPs](https://libsisimai.org/en/engine/)
  * Support Feedback Loop Message(ARF)
  * Can detect [34 bounce reasons](https://libsisimai.org/en/reason/)

[^2]: The callback function allows you to add your own data under the `catch` accessor.

Command line demo
---------------------------------------------------------------------------------------------------
The following screen shows a demonstration of `dump` method of Sisimai 5 at the command line using
Perl(p5-sisimai) and `jq` command.
![](https://libsisimai.org/static/images/demo/sisimai-5-cli-dump-p01.gif)

Setting Up Sisimai
===================================================================================================
System requirements
---------------------------------------------------------------------------------------------------
More details about system requirements are available at
[Sisimai | Getting Started](https://libsisimai.org/en/start/) page.

* [Perl 5.26.0 or later](http://www.perl.org/)
* [__Class::Accessor::Lite__](https://metacpan.org/pod/Class::Accessor::Lite)
* [__JSON__](https://metacpan.org/pod/JSON)

Install
---------------------------------------------------------------------------------------------------
### From CPAN
```shell
$ cpanm --sudo Sisimai
--> Working on Sisimai
Fetching http://www.cpan.org/authors/id/A/AK/AKXLIX/Sisimai-5.7.0.tar.gz ... OK
...
1 distribution installed
$ perldoc -l Sisimai
/usr/local/lib/perl5/site_perl/5.30.0/Sisimai.pm
```

### From GitHub
> [!WARNING]
> Sisimai 5 requires Perl 5.26 or later. Check the version of Perl in your system before installing/upgrading
> by `perl -v` command.

```shell
$ perl -v

This is perl 5, version 30, subversion 0 (v5.30.0) built for darwin-2level

Copyright 1987-2019, Larry Wall
...

$ cd /usr/local/src
$ git clone https://github.com/sisimai/p5-sisimai.git
$ cd ./p5-sisimai

$ make install-from-local
./cpanm --sudo . || ( make cpm && ./cpm install --sudo -v . )
--> Working on .
Configuring Sisimai-v5.7.0 ... OK
Building and testing Sisimai-v5.7.0 ... Password: <sudo password here>
OK
Successfully installed Sisimai-v5.7.0
1 distribution installed

$ perl -MSisimai -lE 'print Sisimai->version'
5.7.0
```

Usage
===================================================================================================
Basic usage
---------------------------------------------------------------------------------------------------
`Sisimai->rise()` method provides the feature for getting decoded data as Perl Hash reference from
bounced email messages as the following. Beginning with v4.25.6, new accessor `origin` which keeps
the path to email file as a data source is available.

```perl
#! /usr/bin/env perl
use Sisimai;
my $v = Sisimai->rise('/path/to/mbox'); # or path to Maildir/


# In v4.23.0, the rise() and dump() methods of the Sisimai class can now read the entire bounce
# email as a string, in addition to the PATH to the email file or mailbox.
use IO::File;
my $r = '';
my $f = IO::File->new('/path/to/mbox'); # or path to Maildir/
{ local $/ = undef; $r = <$f>; $f->close }
my $v = Sisimai->rise(\$r);

# If you also need analysis results that are "delivered" (successfully delivered), please specify
# the "delivered" option to the rise() method as shown below.
my $v = Sisimai->rise('/path/to/mbox', 'delivered' => 1);

# From v5.0.0, Sisimai no longer returns analysis results with a bounce reason of "vacation" by
# default. If you also need analysis results that show a "vacation" reason, please specify the
# "vacation" option to the rise() method as shown in the following code.
my $v = Sisimai->rise('/path/to/mbox', 'vacation' => 1);

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

        print $e->addresser->address;   # "michitsuna@example.org" # From
        print $e->recipient->address;   # "kijitora@example.jp"    # To