• README-JA(日本語)
• What is Sisimai
  • Key features
  • Command line demo
• Setting Up Sisimai
  • System requirements
  • Install
    • From CPAN
    • From GitHub
• Usage
  • Basic usage
  • Convert to JSON
  • Read bounce object
  • Callback feature
  • One-Liner
  • Output example
• Sisimai Specification
  • Differences between bounceHammer and Sisimai
  • Other specification of Sisimai
• Contributing
  • Bug report
  • Emails could not be parsed
• Other Information
  • Related sites
  • See also
• Author
• Copyright
• License

What is Sisimai

Sisimai is a Perl module for analyzing RFC5322 bounce emails and generating structured data from parsed results. Sisimai is the system formerly known as bounceHammer 4. Sisimai is a coined word: Sisi (the number 4 is pronounced Si in Japanese) and MAI (acronym of Mail Analyzing Interface).

Key features

• Convert Bounce Mails to Structured Data
  • Supported formats are Perl(Hash, Array) and JSON(String)
• Easy to Install, Use.
  • cpan, cpanm, or cpm
  • git clone & make
• High Precision of Analysis
  • 2 times higher than bounceHammer
  • Support 22 known MTAs and 5 unknown MTAs
  • Support 22 major MSPs(Mail Service Providers)
  • Support 2 major Cloud Email Delivery Services(JSON format)
  • Support Feedback Loop Message(ARF)
  • Can detect 29 error reasons
• Faster than bounceHammer 2.7.13p3
  • About 1.7 times faster

Command line demo

The following screen shows a demonstration of Sisimai at the command line using Perl(p5-Sisimai) and Ruby(rb-Sisimai) version of Sisimai.

Setting Up Sisimai

System requirements

More details about system requirements are available at Sisimai | Getting Started page.

• Perl 5.10.1 or later
• Class::Accessor::Lite
• JSON

Install

From CPAN

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

From GitHub

shell $ cd /usr/local/src $ git clone https://github.com/sisimai/p5-Sisimai.git $ cd ./p5-Sisimai $ make install-from-local --> Working on . Configuring Sisimai-4.22.0 ... OK 1 distribution installed

Usage

Basic usage

Sisimai->make() method provides feature for getting parsed data as Perl Hash reference from bounced email messages like following.

```perl

! /usr/bin/env perl

use Sisimai; my $v = Sisimai->make('/path/to/mbox'); # or path to Maildir/

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);

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

    my $h = $e->damn();             # Convert to HASH reference
    my $j = $e->dump('json');       # Convert to JSON string
    print $e->dump('json');         # JSON formatted bounce data
}

} ```

Convert to JSON

Sisimai->dump() method provides feature for getting parsed data as JSON string from bounced email messages like following.

```perl

! /usr/bin/env perl

use Sisimai;

Get JSON string from parsed mailbox or Maildir/

my $j = Sisimai->dump('/path/to/mbox'); # or path to Maildir/ # dump() is added in v4.1.27 print $j; # parsed data as JSON

dump() method also accepts "delivered" option like the following code:

my $j = Sisimai->dump('/path/to/mbox', 'delivered' => 1); ```

Read bounce object

The way to read a bounce object retrived from Cloud Email Services as JSON using their API is the following code. This feature is available at Sisimai 4.20.0 or later.

```perl

! /usr/bin/env perl

use JSON; use Sisimai;

my $j = JSON->new; my $q = '{"json":"string",...}' my $v = Sisimai->make($j->decode($q), 'input' => 'json');

if( defined $v ) { for my $e ( @$v ) { ... } } ``` As of present, Only Amazon SES and SendGrid are supported.

Callback feature

Beginning with Sisimai 4.19.0, make() and dump() methods of Sisimai accept a sub routine reference in hook argument for setting a callback method and getting the results generated by the method via Sisimai::Data->catch method.

```perl

! /usr/bin/env perl

use Sisimai; my $callbackto = sub { my $emdata = shift; my $caught = { 'x-mailer' => '', 'queue-id' => '' };

if( $emdata->{'message'} =~ m/^X-Postfix-Queue-ID:\s*(.+)$/m ) {
    $caught->{'queue-id'} = $1;
}

$caught->{'x-mailer'} = $emdata->{'headers'}->{'x-mailer'} || '';
return $caught;

}; my $list = ['X-Mailer']; my $data = Sisimai->make('/path/to/mbox', 'hook' => $callbackto, 'field' => $list); my $json = Sisimai->dump('/path/to/mbox', 'hook' => $callbackto, 'field' => $list);

print $data->0->catch->{'x-mailer'}; # Apple Mail (2.1283) ```

More information about the callback feature is available at Sisimai | How To Parse - Callback Page.

One-Liner

Beginning with Sisimai 4.1.27, dump() method is available and you can get parsed data as JSON using the method.

shell $ perl -MSisimai -lE 'print Sisimai->dump(shift)' /path/to/mbox

Output example

json [{"rhost": "mx.example.co.jp","recipient": "filtered@example.co.jp","token": "01b88ad40b2f7089a6b1986ade14d323aaad9da2","deliverystatus": "5.2.1","smtpcommand": "RCPT","alias": "filtered@example.co.jp","addresser": "kijitora@example.jp","subject": "test","smtpagent": "Email::Postfix","messageid": "","diagnosticcode": "550 5.2.1 <filtered@example.co.jp>... User Unknown","lhost": "smtp.example.com","replycode": "550","reason": "userunknown","destination": "example.co.jp","action": "failed","softbounce": 0,"timezoneoffset": "+0000","diagnostictype": "SMTP","feedbacktype": "","listid": "","timestamp": 1403375674,"senderdomain": "example.jp"},{"lhost": "smtp.example.com","reason": "userunknown","replycode": "550","destination": "example.co.jp","action": "failed","softbounce": 0,"timezoneoffset": "+0000","diagnostictype": "SMTP","feedbacktype": "","listid": "","timestamp": 1403375674,"senderdomain": "example.jp","rhost": "mx.example.co.jp","recipient": "userunknown@example.co.jp","deliverystatus": "5.1.1","token": "948ed89b794207632dbab0ce3b72175553d9de83","smtpcommand": "RCPT","alias": "userunknown@example.co.jp","addresser": "kijitora@example.jp","subject": "test","smtpagent": "Email::Postfix","messageid": "","diagnosticcode": "550 5.1.1 <userunknown@example.co.jp>... User Unknown"}]

Sisimai Specification

Differences between bounceHammer and Sisimai

The following table show the differences between ver.2 (bounceHammer 2.7.13p3) and Sisimai. More information about differences are available at Sisimai | Differences page.

1. Implement yourself with using DBI or any O/R Mapper you like 2. See ./ANALYTICAL-PRECISION

Other specification of Sisimai

• Parser Engines
• Bounce Reason List
• Data Structure of Sisimai::Data

Contributing

Bug report

Please use the issue tracker to report any bugs.

Emails could not be parsed

Bounce mails which could not be parsed by Sisimai are saved in the repository set-of-emails/to-be-debugged-because/sisimai-cannot-parse-yet. If you have found any bounce email cannot be parsed using Sisimai, please add the email into the directory and send Pull-Request to this repository.

Other Information

Related sites

• @libsisimai | Sisimai on Twitter (@libsisimai)
• libSISIMAI.ORG | Sisimai | The Successor To bounceHammer, Library to parse bounce mails
• Sisimai Blog | blog.libsisimai.org
• Facebook Page | facebook.com/libsisimai
• GitHub | github.com/sisimai/p5-Sisimai
• CPAN | Sisimai - Mail Analyzing Interface for bounce mails. - metacpan.org
• CPAN Testers Reports | CPAN Testers Reports: Reports for Sisimai
• Ruby verson | Ruby version of Sisimai
• Fixtures | set-of-emails - Sample emails for "make test"
• bounceHammer.JP | bounceHammer will be EOL on February 29, 2016

See also

• README-JA.md - README.md in Japanese(日本語)
• RFC3463 - Enhanced Mail System Status Codes
• RFC3464 - An Extensible Message Format for Delivery Status Notifications
• RFC3834 - Recommendations for Automatic Responses to Electronic Mail
• RFC5321 - Simple Mail Transfer Protocol
• RFC5322 - Internet Message Format

Author

@azumakuniyuki

Copyright

Copyright (C) 2014-2017 azumakuniyuki, All Rights Reserved.

License

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