- README-JA(日本語)
- What is Sisimai
- Setting Up Sisimai
- Usage
- Sisimai Specification
- Contributing
- Other Information
- Author
- Copyright
- License
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).
- Convert Bounce Mails to Structured Data
- Supported formats are Perl(Hash, Array) and JSON(String)
- Easy to Install, Use.
cpan,cpanm, orcpm- git clone & make
- High Precision of Analysis
- 2 times higher than bounceHammer
- Support 68 MTAs/MDAs/ESPs
- Support Feedback Loop Message(ARF)
- Can detect 29 error reasons
- Faster than bounceHammer 2.7.13p3
- About 2.0 times faster
The following screen shows a demonstration of Sisimai at the command line using
Perl(p5-sisimai) and Ruby(rb-sisimai) version of Sisimai.
More details about system requirements are available at Sisimai | Getting Started page.
$ cpanm --sudo Sisimai
--> Working on Sisimai
Fetching http://www.cpan.org/authors/id/A/AK/AKXLIX/Sisimai-4.25.5.tar.gz ... OK
...
1 distribution installed
$ perldoc -l Sisimai
/usr/local/lib/perl5/site_perl/5.30.0/Sisimai.pm$ 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.25.5 ... OK
1 distribution installedSisimai->make() method provides feature for getting parsed data as Perl Hash
reference from bounced email messages like following. Beginning with v4.25.6,
new accessor origin which keeps the path to email file as a data source is
available.
#! /usr/bin/env perl
use Sisimai;
my $v = Sisimai->make('/path/to/mbox'); # or path to Maildir/
# Beginning with v4.23.0, both make() and dump() method of Sisimai class can
# read bounce messages from variable instead of a path to 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->make(\$r);
# 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
print $e->origin; # /var/spool/bounce/new/1740074341.eml
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
}
}Sisimai->dump() method provides feature for getting parsed data as JSON string
from bounced email messages like following.
#! /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);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.
#! /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 $data = Sisimai->make('/path/to/mbox', 'hook' => $callbackto);
my $json = Sisimai->dump('/path/to/mbox', 'hook' => $callbackto);
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.
Beginning with Sisimai 4.1.27, dump() method is available and you can get parsed
data as JSON using the method.
$ perl -MSisimai -lE 'print Sisimai->dump(shift)' /path/to/mbox
[{"smtpagent": "Sendmail","reason": "hasmoved","recipient": "kijitora@example.net","replycode": "","senderdomain": "example.co.jp","alias": "","timezoneoffset": "+0900","deliverystatus": "5.1.6","timestamp": 1397086485,"origin": "set-of-emails/maildir/bsd/lhost-sendmail-22.eml","catch": {"x-mailer": "","queue-id": "","sender": ""},"destination": "example.net","subject": "Nyaaaan","lhost": "localhost","rhost": "mx-s.neko.example.jp","listid": "","messageid": "0000000011111.fff0000000003@mx.example.co.jp","addresser": "shironeko@example.co.jp","action": "failed","diagnostictype": "SMTP","smtpcommand": "DATA","feedbacktype": "","token": "61b5ea94209460ac018c1a2060bdab0acce9ffed","softbounce": 0,"diagnosticcode": "450 busy - please try later 551 not our customer 503 need RCPT command [data]"}]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.
| Features | bounceHammer | Sisimai |
|---|---|---|
| System requirements(Perl) | 5.10 - 5.14 | 5.10 - 5.30 |
| Command line tools | Available | N/A |
| Modules for Commercial MTAs and MPSs | N/A | Included |
| WebUI/API | Included | N/A |
| Database schema for storing parsed bounce data | Available | N/A[1] |
| Analytical precision ratio(2000 emails)[2] | 0.61 | 1.00 |
| The speed of parsing email(1000 emails) | 4.24s | 1.35s[3] |
| The number of detectable bounce reasons | 19 | 29 |
| The number of MTA modules(parser engine) | 15 | 68 |
| Parse 2 or more bounces in a single email | Only 1st rcpt | ALL |
| Parse FeedBack Loop Message/ARF format mail | Unable | OK |
| Classification based on recipient domain | Available | N/A |
| Output format of parsed data | YAML,JSON,CSV | JSON only |
| Easy to install | No | Yes |
| Install using cpan, cpanm, or cpm command | N/A | OK |
| Dependencies (Except core modules of Perl) | 24 modules | 2 modules |
| LOC:Source lines of code | 18200 lines | 10500 lines |
| The number of tests in t/, xt/ directory | 27365 tests | 265000 tests |
| License | GPLv2 or Perl | 2 clause BSD |
| Support Contract provided by Developer | End Of Sales | Available |
- Implement yourself with using DBI or any O/R Mapper you like
- See ./ANALYTICAL-PRECISION
- Xeon E5-2640 2.5GHz x 2 cores | 5000 bogomips | 1GB RAM | Perl 5.24.1
Please use the issue tracker to report any bugs.
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.
- @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
- 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
Copyright (C) 2014-2020 azumakuniyuki, All Rights Reserved.
This software is distributed under The BSD 2-Clause License.