/ 
Sisimai-v4.25.5
⭐ Starred 78 / README-JA.md

License Coverage Status Build Status Perl CPAN

What is sisimai

Sisimai(シシマイ)はRFC5322準拠のエラーメールを解析し、解析結果をデータ構造に 変換するインターフェイスを提供するPerlモジュールです。 シシマイ はbounceHammer version 4として開発していたものであり、Version 4なので シ(Si) から始まりマイ(MAI: Mail Analyzing Interface)を含む名前になりました。

Key features

Command line demo

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

Setting Up Sisimai

System requirements

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

Install

From CPAN

$ 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

From GitHub

$ 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.25.5 ... OK
1 distribution installed

Usage

Basic usage

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

#! /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

        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)で返ってきます。

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

Callback feature

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

#! /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化した 解析結果が得られます。

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

Output example

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

  1. DBIまたは好きなORMを使って自由に実装してください
  2. ./ANALYTICAL-PRECISIONを参照
  3. Xeon E5-2640 2.5GHz x 2 cores | 5000 bogomips | 1GB RAM | Perl 5.24.1

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

See also

Author

@azumakuniyuki

Copyright

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

License

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