azuma, kuniyuki
and 7 contributors


Sisimai - Mail Analyzing Interface for bounce mails.


    use Sisimai;


Sisimai is the system formerly known as bounceHammer 4, is a Pelr module for analyzing bounce mails and generate structured data in a JSON format (YAML is also available if "YAML" module is installed on your system) from parsed bounce messages. Sisimai is a coined word: Sisi (the number 4 is pronounced "Si" in Japanese) and MAI (acronym of "Mail Analyzing Interface").


make('/path/to/mbox', delivered = 1)>

make method provides feature for getting parsed data from bounced email messages like following.

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

    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;   # # From
            print $e->recipient->address;   #   # To
            print $e->recipient->host;      #
            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
            my $y = $e->dump('yaml');       # Convert to YAML string

        # Dump entire list as a JSON 
        use JSON '-convert_blessed_universally';
        my $json = JSON->new->allow_blessed->convert_blessed;

        printf "%s\n", $json->encode($v);

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

dump('/path/to/mbox', delivered = 1)>

dump method provides feature to get parsed data from bounced email as JSON.

    use Sisimai;
    my $v = Sisimai->dump('/path/to/mbox'); # or Path to Maildir
    print $v;                               # JSON string


Read email data from STDIN

If you want to pass email data from STDIN, specify STDIN at the first argument of dump() and make() method like following command:

    % cat ./path/to/bounce.eml | perl -MSisimai -lE 'print Sisimai->dump(STDIN)'

Callback Feature

Beggining from v4.19.0, `hook` argument is available to callback user defined method like the following codes: my $cmethod = sub { my $argv = shift; my $data = { 'queue-id' => '', 'x-mailer' => '', 'precedence' => '', };

        # Header part of the bounced mail
        for my $e ( 'x-mailer', 'precedence' ) {
            next unless exists $argv->{'headers'}->{ $e };
            $data->{ $e } = $argv->{'headers'}->{ $e };

        # Message body of the bounced email
        if( $argv->{'message'} =~ m/^X-Postfix-Queue-ID:\s*(.+)$/m ) {
            $data->{'queue-id'} = $1;

        return $data;

    my $message = Sisimai::Message->new(
        'data' => $mailtxt, 
        'hook' => $cmethod,
        'field' => ['X-Mailer', 'Precedence']
    print $message->catch->{'x-mailer'};    # Apple Mail (2.1283)
    print $message->catch->{'queue-id'};    # 2DAEB222022E
    print $message->catch->{'precedence'};  # bulk



engine method provides table including parser engine list and its description.

    use Sisimai;
    my $v = Sisimai->engine();
    for my $e ( keys %$v ) {
        print $e;           # Sisimai::MTA::Sendmail
        print $v->{ $e };   # V8Sendmail: /usr/sbin/sendmail


reason method provides table including all the reasons Sisimai can detect

    use Sisimai;
    my $v = Sisimai->reason();
    for my $e ( keys %$v ) {
        print $e;           # Blocked
        print $v->{ $e };   # 'Email rejected due to client IP address or a hostname'


Sisimai::Mail - Mailbox or Maildir object
Sisimai::Data - Parsed data object - Sisimai — A successor to bounceHammer, Library to parse error mails - RFC3463: Enhanced Mail System Status Codes - RFC3464: An Extensible Message Format for Delivery Status Notifications - RFC5321: Simple Mail Transfer Protocol - RFC5322: Internet Message Format

REPOSITORY - Sisimai on GitHub

WEB SITE - A successor to bounceHammer, Library to parse error mails. - Ruby version of Sisimai




Copyright (C) 2014-2017 azumakuniyuki, All rights reserved.


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