/ 
Sisimai-v4.25.10
River stage zero No dependents
/ Sisimai

NAME

Sisimai - Mail Analyzing Interface for bounce mails.

SYNOPSIS

use Sisimai;

DESCRIPTION

Sisimai is a Mail Analyzing Interface for email bounce, is a Perl module to parse RFC5322 bounce mails and generating structured data as JSON from parsed results. 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/
#  $v = Sisimai->make(\'From Mailer-Daemon ...');

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
        print $e->origin;               # /var/spool/bounce/2022-2222.eml

        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,
);
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'
}

match()

match method receives an error message as a string and returns a reason name like the following:

use Sisimai;
my $v = '550 5.1.1 User unknown';
my $r = Sisimai->match($v);
print $r;   # "userunknown"

version()

version method returns the version number of Sisimai.

use Sisimai;
print Sisimai->version; # 4.25.0p5

SEE ALSO

Sisimai::Mail - Mailbox or Maildir object
Sisimai::Data - Parsed data object
https://libsisimai.org/ - Sisimai — 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-2020 azumakuniyuki, All rights reserved.

LICENSE

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