README(English)
シシマイ? | What is Sisimai
- 主な特徴的機能 | Key features
- コマンドラインでのデモ | command line demo
シシマイを使う準備 | Setting Up Sisimai
- 動作環境 | System requirements
- インストール | Install
  - CPANから | From CPAN
  - GitHubから | From GitHub
使い方 | Usage
シシマイの仕様 | Sisimai Specification
- bounceHammerとSisimaiの違い | Differences
- その他の仕様詳細 | 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(シシマイ)はRFC5322準拠のエラーメールを解析し、解析結果をデータ構造に変換するインターフェイスを提供するPerlモジュールです。 シシマイ はbounceHammer version 4として開発していたものであり、Version 4なので シ(Si) から始まりマイ(MAI: Mail Analyzing Interface)を含む名前になりました。

Key features

エラーメールをデータ構造に変換
- Perlのデータ形式(HashとArray)とJSON(文字列)に対応
インストールも使用も簡単
- cpan, cpanm, cpm install
- git clone & make
高い解析精度
- 解析精度はbounceHammerの2倍
- 28種類のMTAに対応
- 22種類の著名なMSPに対応
- 2種類の著名なメール配信クラウドに対応(JSON)
- Feedback Loopにも対応
- 29種類のエラー理由を検出
bounceHammer 2.7.13p3よりも高速に解析
- 1.7倍程高速

Command line demo

次の画像のように、Perl版シシマイ(p5-Sisimai)もRuby版シシマイ(rb-Sisimai)も、コマンドラインから簡単にバウンスメールを解析することができます。

Setting Up Sisimai

System requirements

シシマイの動作環境についての詳細は Sisimai | シシマイを使ってみるをご覧ください。

Install

From CPAN

shell $ cpanm --sudo Sisimai --> Working on Sisimai Fetching http://www.cpan.org/authors/id/A/AK/AKXLIX/Sisimai-4.22.2.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 $ sudo make install-from-local --> Working on . Configuring Sisimai-4.22.2 ... OK 1 distribution installed

Usage

Basic usage

下記のようにSisimaiのmake()メソッドをmboxかMaildirのPATHを引数にして実行すると解析結果が配列リファレンスで返ってきます。

```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()メソッドをmboxかMaildirのPATHを引数にして実行すると解析結果が文字列(JSON)で返ってきます。

```perl

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

メール配信クラウドからAPIで取得したバウンスオブジェクト(JSON)を読んで解析する場合は、次のようなコードを書いてください。この機能はSisimai v4.20.0で実装されました。

```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 ) { ... } } ``` 現時点ではAmazon SESとSendGridのみをサポートしています。

Callback feature

Sisimai 4.19.0からSisimai->make()とSisimai->dump()にコードリファレンスを引数hookに指定できるコールバック機能が実装されました。 hookに指定したサブルーチンによって処理された結果はSisimai::Data->catch メソッドで得ることができます。

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

コールバック機能のより詳細な使い方は Sisimai | 解析方法 - コールバック機能をご覧ください。

One-Liner

Sisimai 4.1.27から登場したdump()メソッドを使うとワンライナーでJSON化した解析結果が得られます。

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

Output example

json [{"recipient": "kijitora@example.jp", "addresser": "shironeko@1jo.example.org", "feedbacktype": "", "action": "failed", "subject": "Nyaaaaan", "smtpcommand": "DATA", "diagnosticcode": "550 Unknown user kijitora@example.jp", "listid": "", "destination": "example.jp", "smtpagent": "Email::Courier", "lhost": "1jo.example.org", "deliverystatus": "5.0.0", "timestamp": 1291954879, "messageid": "201012100421.oBA4LJFU042012@1jo.example.org", "diagnostictype": "SMTP", "timezoneoffset": "+0900", "reason": "filtered", "token": "ce999a4c869e3f5e4d8a77b2e310b23960fb32ab", "alias": "", "senderdomain": "1jo.example.org", "rhost": "mfsmax.example.jp"}, {"diagnostictype": "SMTP", "timezoneoffset": "+0900", "reason": "userunknown", "timestamp": 1381900535, "messageid": "E1C50F1B-1C83-4820-BC36-AC6FBFBE8568@example.org", "token": "9fe754876e9133aae5d20f0fd8dd7f05b4e9d9f0", "alias": "", "senderdomain": "example.org", "rhost": "mx.bouncehammer.jp", "action": "failed", "addresser": "kijitora@example.org", "recipient": "userunknown@bouncehammer.jp", "feedbacktype": "", "smtpcommand": "DATA", "subject": "バウンスメールのテスト(日本語)", "destination": "bouncehammer.jp", "listid": "", "diagnosticcode": "550 5.1.1 <userunknown@bouncehammer.jp>... User Unknown", "deliverystatus": "5.1.1", "lhost": "p0000-ipbfpfx00kyoto.kyoto.example.co.jp", "smtpagent": "Email::Sendmail"}]

Sisimai Specification

Differences between bounceHammer and Sisimai

bounceHammer 2.7.13p3とSisimai(シシマイ)は下記のような違いがあります。違いの詳細についてはSisimai | 違いの一覧をご覧ください。

機能	bounceHammer	Sisimai
動作環境(Perl)	5.10 - 5.14	5.10 - 5.26
コマンドラインツール	あり	無し
商用MTAとMSP対応解析モジュール	無し	あり(同梱)
WebUIとAPI	あり	無し
解析済バウンスデータを保存するDBスキーマ	あり	無し1
解析精度の割合(2000通のメール)2	0.49	1.00
メール解析速度(1000通のメール)	4.24秒	1.95秒
検出可能なバウンス理由の数	19	29
2件以上のバウンスがあるメールの解析	1件目だけ	全件解析可能
FeedBack Loop/ARF形式のメール解析	非対応	対応済
宛先ドメインによる分類項目	あり	無し
解析結果の出力形式	YAML,JSON,CSV	JSON
インストール作業が簡単かどうか	やや面倒	簡単で楽
cpan, cpanm, cpmコマンドでのインストール	非対応	対応済
依存モジュール数(Perlのコアモジュールを除く)	24モジュール	2モジュール
LOC:ソースコードの行数	18200行	8700行
テスト件数(t/,xt/ディレクトリ)	27365件	230000件
ライセンス	GPLv2かPerl	二条項BSD
開発会社によるサポート契約	終売(EOS)	提供中

1. DBIまたは好きなORMを使って自由に実装してください 2. ./ANALYTICAL-PRECISIONを参照

Other spec of Sisimai

Contributing

Bug report

もしもSisimaiにバグを発見した場合はIssues にて連絡をいただけると助かります。

Emails could not be parsed

Sisimaiで解析できないバウンスメールは set-of-emails/to-be-debugged-because/sisimai-cannot-parse-yetリポジトリに追加してPull-Requestを送ってください。

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

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

What is sisimai

Key features

Command line demo

Setting Up Sisimai

System requirements

Install

From CPAN

From GitHub

Usage

Basic usage

! /usr/bin/env perl

If you want to get bounce records which reason is "delivered", set "delivered"

option to make() method like the following:

Convert to JSON

Get JSON string from parsed mailbox or Maildir/

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

Read bounce object

! /usr/bin/env perl

Callback feature

! /usr/bin/env perl

One-Liner

Output example

Sisimai Specification

Differences between bounceHammer and Sisimai

Other spec of Sisimai

Contributing

Bug report

Emails could not be parsed

Other Information

Related sites

See also

Author

Copyright

License