Get Started

Environment

Sisimai works on some operating systems that Perl or Ruby (including JRuby) is available to execute except Windows.

Read

How To Install

Sisimai could be downloaded and installed from CPAN, RubyGems.org, and GitHub repository.

Read

Basic Usage

How to use Sisimai to parse bounce mails, to get structured data, and for converting parsed data as JSON.

Read

How To Parse

How to read bounce mail data from Standard-In, to include a delivery success in the parsed results, and to use callback feature.

Read

System Requirements

Sisimai can run on the system that Perl or Ruby (Including JRuby) is available like the following lists, such as *BSD, Mac OS X, and Linux. However, as of the present, Sisimai does not work (make test fails) with ActivePerl and other Perl implementations on Windows. .

Perl 5.10.1 or later

Download from CPAN

Ruby 2.1.0 or later

  • Also works on JRuby 9.0.4.0-
  • Runtime dependencies in MRI
  • Runtime dependencies in JRuby
Download from RubyGems

Install Sisimai

Sisimai could be downloaded and installed from GitHub, CPAN, and RubyGems.org .

From GitHub

The latest version of Sisimai including development version and stable version is available to download from the GitHub master branch. Both the Perl and the Ruby version are available in the repository.

Perl

Perl version of Sisimai

A repository name of the Perl version Sisimai is sisimai/p5-Sisimai.

% git clone https://github.com/sisimai/p5-Sisimai.git
% cd ./p5-Sisimai
% sudo make install-from-local
--> Working on .
Configuring Sisimai-4.20.0 ... OK
1 distribution installed
                
Ruby

Ruby version of Sisimai

A repository name of the Ruby version Sisimai is sisimai/rb-Sisimai.

% git clone https://github.com/sisimai/rb-Sisimai.git
% cd ./rb-Sisimai
% sudo make depend install-from-local
gem install bundle rake rspec coveralls
...
sisimai 4.20.0 built to pkg/sisimai-4.20.0.gem.
sisimai (4.20.0) installed.
                
Perl

From CPAN

Only the stable version of Sisimai is available to download from CPAN. You can install the software using cpan command, however, cpanm command is very useful to install the software and other Perl modules.

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

From RubyGems.org

Only the stable version of Sisimai is available to download from RubyGems.org. You can install the software using gem command.

% sudo gem install sisimai
Fetching: sisimai-4.20.0.gem (100%)
Successfully installed sisimai-4.20.0
Parsing documentation for sisimai-4.20.0
Installing ri documentation for sisimai-4.20.0
Done installing documentation for sisimai after 6 seconds
1 gem installed
                

Basic Usage

make()

make() method of Sisimai

For example, the following code shows that make() method of Sisimai provides the feature for getting parsed data from bounced email messages. Other arguments of make() method are available at How To Parse page.

Perl

Perl version of Sisimai

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

if( defined $v ) {
    for my $e ( @$v ) {
        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
    }
} else {
    # There is no bounce message in the mailbox
    # or Sisimai could not parse
}
                
Ruby

Ruby version of Sisimai

#! /usr/bin/env ruby
require 'sisimai'
v = Sisimai.make('/path/to/mbox') # or Path to Maildir

if v.is_a? Array
  v.each do |e|
    puts e.addresser.address    # shironeko@example.org # From
    puts e.recipient.address    # kijitora@example.jp   # To
    puts e.recipient.host       # example.jp
    puts e.deliverystatus       # 5.1.1
    puts e.replycode            # 550
    puts e.reason               # userunknown
  end
else
  # There is no bounce message in the mailbox
  # or Sisimai could not parse
end
                
dump()

dump() method of Sisimai

Beginning with the Perl version of Sisimai v4.1.27, dump() method of Sisimai is useful to get the parsed results as JSON. The following sample code shows that usage of dump() method with a path to Maildir/ you want to parse at the first argument.

Perl

Perl version of Sisimai

#! /usr/bin/env perl
use Sisimai;
print Sisimai->dump('~/Maildir/cur');
                
Ruby

Ruby version of Sisimai

#! /usr/bin/env ruby
require 'sisimai'
puts Sisimai.dump('~/Maildir/cur')
                
Demo

Demonstration of the dump method

jq

Filter using "jq" utility

If you would like to make sure of parsed results, you may want to install jq utility. The following command shows that "jq" utility will be easier to read the parsed data generated by dump() method.

Perl

Perl version of Sisimai

% perl -MSisimai -lE 'print Sisimai->dump(shift)' path/to/mbox | jq .
                
Ruby

Ruby version of Sisimai

% ruby -rsisimai -e 'puts Sisimai.dump($*.shift)' path/to/mbox | jq .
                
Demo

Demonstration of the dump method with jq

JSON

JSON string filtered by jq utility

[
  {
    "smtpcommand": "DATA",
    "timestamp": 1397054085,
    "action": "failed",
    "listid": "",
    "reason": "hasmoved",
    "deliverystatus": "5.1.6",
    "smtpagent": "Sendmail",
    "destination": "example.net",
    "timezoneoffset": "+0900",
    "feedbacktype": "",
    "diagnostictype": "SMTP",
    "senderdomain": "example.co.jp",
    "rhost": "mx-s.neko.example.jp",
    "lhost": "localhost",
    "catch": "",
    "addresser": "shironeko@example.co.jp",
    "replycode": "551",
    "messageid": "0000000011111.fff0000000003@mx.example.co.jp",
    "token": "cf17945938502bd876603a375f0e9517c921bbab",
    "recipient": "kijitora@example.net",
    "alias": "",
    "diagnosticcode": "551 not our customer",
    "subject": "Nyaaaan",
    "softbounce": 0
  }
]