Scroll to navigation

Sisimai(3pm) User Contributed Perl Documentation Sisimai(3pm)

NAME

Sisimai - Mail Analyzing Interface for bounce mails.

SYNOPSIS

    use Sisimai;

DESCRIPTION

Sisimai is the system formerly known as "bounceHammer" 4, is a Perl 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").

BASIC USAGE

"make('/path/to/mbox')"

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

"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

OTHER WAYS TO PARSE

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

Beginning 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'} =~ /^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

OTHER METHODS

"engine()"

"engine" method provides table including parser engine list and it's 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()"

"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'
    }

SEE ALSO

Sisimai::Mail - Mailbox or Maildir object
Sisimai::Data - Parsed data object
<https://libsisimai.org/> - Sisimai X A successor to bounceHammer, Library to parse error mails
<https://tools.ietf.org/html/rfc3463> - RFC3463: Enhanced Mail System Status Codes
<https://tools.ietf.org/html/rfc3464> - RFC3464: An Extensible Message Format for Delivery Status Notifications
<https://tools.ietf.org/html/rfc5321> - RFC5321: Simple Mail Transfer Protocol
<https://tools.ietf.org/html/rfc5322> - RFC5322: Internet Message Format

REPOSITORY

<https://github.com/sisimai/p5-Sisimai> - Sisimai on GitHub

WEB SITE

<https://libsisimai.org/> - A successor to bounceHammer, Library to parse error mails.

<https://github.com/sisimai/rb-Sisimai> - Ruby version of Sisimai

AUTHOR

azumakuniyuki

COPYRIGHT

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

LICENSE

This software is distributed under The BSD 2-Clause License.
2018-06-23 perl v5.24.1