[![Build Status](https://travis-ci.org/azumakuniyuki/p5-Sisimai.svg?branch=master)](https://travis-ci.org/azumakuniyuki/p5-Sisimai) 
[![Coverage Status](https://img.shields.io/coveralls/azumakuniyuki/p5-Sisimai.svg)](https://coveralls.io/r/azumakuniyuki/p5-Sisimai)

![](http://41.media.tumblr.com/45c8d33bea2f92da707f4bbe66251d6b/tumblr_nuf7bgeyH51uz9e9oo1_1280.png)

What is Sisimai ? | ������������?
=============================
Sisimai is a Perl module for analyzing RFC5322 bounce emails and generating
structured data from parsed results. Sisimai is the system formerly known as
bounceHammer 4. "Sisimai" is a coined word: Sisi (the number 4 is pronounced
"Si" in Japanese) and MAI (acronym of "Mail Analyzing Interface").

Sisimai(������������)���RFC5322���������������������������������������������������������������������������
���������������������������������������������������Perl������������������������
"������������"���bounceHammer version 4���������������������������������������������Version 4���������
"���"���������������������(MAI: Mail Analyzing Interface)������������������������������������

Features | ������������
-------------------
* __Convert bounce mails to structured data__ | __���������������������������������������������__
  * Supported formats are Perl, JSON | Perl���������������������JSON���������
* __Easy to install, use.__ | __������������������������������������__
  * cpanm
  * git clone
* __High analytical precision__ | __������������������__
  * Support 21 known MTAs and 4 unknown MTAs | 25���������MTA���������
  * Support 19 major MSPs(Mail Service Providers) | 19������������������MSP���������
  * Support Feedback Loop Message(ARF) | Feedback Loop������������
  * Can detect 25 error reasons | 25���������������������������������
* __Faster than bounceHammer version 2.7.X__ | __bounceHammer 2.7.X������������������������__


Setting Up Sisimai | ���������������������������
=======================================

System requirements | ������������
------------------------------
More details about system requirements are available at available at 
[Sisimai ��� How to Install and Start](http://libsisimai.org/start) page.

* [Perl 5.10.1 or later](http://www.perl.org/)
* [__Class::Accessor::Lite__](https://metacpan.org/pod/Class::Accessor::Lite)
* [__JSON__](https://metacpan.org/pod/JSON)


Install | ������������������
----------------------

### From CPAN

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

### From GitHub

    % cd /usr/local/src
    % git clone https://github.com/azumakuniyuki/p5-Sisimai.git
    % cd ./p5-Sisimai
    % sudo make install-from-local
    --> Working on .
    Configuring Sisimai-4.1.20 ... OK
    1 distribution installed


Usage | ���������
==============

Basic usage | ���������������������
----------------------------
make() method provides feature for getting parsed data from bounced email 
messages like following.

```perl
#! /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 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
    }
}

# 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

```

```json
[{"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": "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": "Sendmail"}]
```

������������������Sisimai���make()���������������mbox���Maildir���PATH���������������������������������
���������������������������������������������������������������

One-Liner | ���������������������
--------------------------

Beginning with Sisimai 4.1.27, dump() method is available and you can get parsed
data as JSON using the method.

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

Sisimai 4.1.27������������������dump()���������������������������������������������JSON���������������������
���������������������


Sisimai Specification | ���������������������
======================================

Differences between ver.2 and Sisimai | ���������������
--------------------------------------------------
The followings are the differences between version 2 (bounceHammer 2.7.13) and
Sisimai.

| Features                                       | bounceHammer  | Sisimai     |
|------------------------------------------------|---------------|-------------|
| System requirements(Perl)                      | 5.10 - 5.14   | 5.10 - 5.22 |
| Command line tools                             | Available     | N/A         |
| Modules for Commercial MTAs and MPSs           | N/A           | Included    |
| WebUI/API                                      | Included      | N/A         |
| Database schema for storing parsed bounce data | Available     | N/A(1)      |
| Analytical precision ratio(2000 files) (2)     | 0.50          | 1.00        |
| The speed of parsing email(2000 files)         | 7.07s         | 4.70s       |
| Parse 2 or more bounces in a single email      | Only 1st rcpt | ALL         |
| Parse FeedBack Loop Message/ARF format mail    | N/A           | OK          |
| Classification based on recipient domain       | Available     | N/A         |
| Output format of parsed data                   | YAML,JSON,CSV | JSON only   |
| Easy to install                                | No            | Yes         |
| Install using cpan or cpanm command            | N/A           | OK          |
| Dependencies (Except core modules of Perl)     | 24 modules    | 2 modules   |
| LOC:Source lines of code                       | 18200 lines   | 7800 lines  |
| The number of tests in t/ directory            | 27365 tests   | 149300 tests|
| License                                        | GPLv2 or Perl | 2 clause BSD|
| Support Contract provided by Developer         | Available     | Coming soon |

1. Implement yourself with using DBI or any O/R Mapper you like
2. See ./ANALYTICAL-PRECISION

������������bouncehammer version 2.7.13���Sisimai(������������)���������������������������������������������

| ������                                           | bounceHammer  | Sisimai     |
|------------------------------------------------|---------------|-------------|
| ������������(Perl)                                 | 5.10 - 5.14   | 5.10 - 5.22 |
| ������������������������������                           | ������          | ������        |
| ������MTA���MSP���������������������������                 | ������          | ������(������)  |
| WebUI���API                                     | ������          | ������        |
| ���������������������������������������������DB������������       | ������          | ������(1)     |
| ���������������������(2000���)(2)                      | 0.50          | 1.00        |
| ���������������������(2000���)                         | 7.07���        | 4.70���      |
| 2���������������������������������������������������            | 1������������     | ������������    |
| FeedBack Loop/ARF������������������������              | ���������        | ���������      |
| ���������������������������������������                     | ������          | ������        |
| ���������������������������                             | YAML,JSON,CSV | JSON������    |
| ���������������������������������������������                 | ������������      | ������������    |
| cpan���������cpanm������������������������������������        | ���������        | ���������      |
| ������������������������(Perl���������������������������������)   | 24���������������  | 2��������������� |
| LOC:���������������������������                         | 18200���       | 7800���      |
| ���������������(t/������������������)                     | 27365���       | 149300���    |
| ���������������                                     | GPLv2���Perl   | ���������BSD   |
| ���������������������������������������                     | ���������        | ���������      |

1. DBI������������������ORM���������������������������������������������
2. ./ANALYTICAL-PRECISION���������


MTA/MSP Modules | MTA/MSP���������������������
---------------------------------------
The following table is the list of MTA/MSP:(Mail Service Provider) modules.

| Module Name(Sisimai::)   | Description                                       |
|--------------------------|---------------------------------------------------|
| MTA::Activehunter        | TransWARE Active!hunter                           |
| MTA::ApacheJames         | Java Apache Mail Enterprise Server(> v4.1.26)     |
| MTA::Courier             | Courier MTA                                       |
| MTA::Domino              | IBM Domino Server                                 |
| MTA::Exchange            | Microsoft Exchange Server                         |
| MTA::Exim                | Exim                                              |
| MTA::IMailServer         | IPSWITCH IMail Server                             |
| MTA::InterScanMSS        | Trend Micro InterScan Messaging Security Suite    |
| MTA::MXLogic             | McAfee SaaS                                       |
| MTA::MailFoundry         | MailFoundry                                       |
| MTA::MailMarshalSMTP     | Trustwave Secure Email Gateway                    |
| MTA::McAfee              | McAfee Email Appliance                            |
| MTA::MessagingServer     | Oracle Communications Messaging Server            |
| MTA::mFILTER             | Digital Arts m-FILTER                             |
| MTA::Notes               | Lotus Notes                                       |
| MTA::OpenSMTPD           | OpenSMTPD                                         |
| MTA::Postfix             | Postfix                                           |
| MTA::qmail               | qmail                                             |
| MTA::Sendmail            | V8Sendmail: /usr/sbin/sendmail                    |
| MTA::SurfControl         | WebSense SurfControl                              |
| MTA::V5sendmail          | Sendmail version 5                                |
| MTA::X1                  | Unknown MTA #1                                    |
| MTA::X2                  | Unknown MTA #2                                    |
| MTA::X3                  | Unknown MTA #3                                    |
| MTA::X4                  | Unknown MTA #4 qmail clones(> v4.1.23)            |
| MSP::DE::EinsUndEins     | 1&1: http://www.1and1.de                          |
| MSP::DE::GMX             | GMX: http://www.gmx.net                           |
| MSP::JP::Biglobe         | BIGLOBE: http://www.biglobe.ne.jp                 |
| MSP::JP::EZweb           | au EZweb: http://www.au.kddi.com/mobile/          |
| MSP::JP::KDDI            | au by KDDI: http://www.au.kddi.com                |
| MSP::RU::MailRu          | @mail.ru: https://mail.ru                         |
| MSP::RU::Yandex          | Yandex.Mail: http://www.yandex.ru                 |
| MSP::UK::MessageLabs     | Symantec.cloud http://www.messagelabs.com         |
| MSP::US::AmazonSES       | AmazonSES(Sending): http://aws.amazon.com/ses/    |
| MSP::US::Aol             | Aol Mail: http://www.aol.com                      |
| MSP::US::Bigfoot         | Bigfoot: http://www.bigfoot.com                   |
| MSP::US::Facebook        | Facebook: https://www.facebook.com                |
| MSP::US::Google          | Google Gmail: https://mail.google.com             |
| MSP::US::Outlook         | Microsoft Outlook.com: https://www.outlook.com/   |
| MSP::US::ReceivingSES    | AmazonSES(Receiving): http://aws.amazon.com/ses/  |
| MSP::US::SendGrid        | SendGrid: http://sendgrid.com/                    |
| MSP::US::Verizon         | Verizon Wireless: http://www.verizonwireless.com  |
| MSP::US::Yahoo           | Yahoo! MAIL: https://www.yahoo.com                |
| MSP::US::Zoho            | Zoho Mail: https://www.zoho.com                   |
| ARF                      | Abuse Feedback Reporting Format                   |
| RFC3464                  | Fallback Module for MTAs                          |
| RFC3834                  | Detector for auto replied message (> v4.1.28)     |

���������Sisimai������������������MTA/MSP(������������������������������������)���������������������������������


Bounce Reason List | ���������������������������
----------------------------------------
Sisimai can detect the following 25 bounce reasons. More details about reasons
are available at [Sisimai ��� Bounce Reason List Sisimai detects](http://libsisimai.org/reason)
page.

| Reason(������)   | Description                            | ���������������                       |
|----------------|----------------------------------------|----------------------------------|
| Blocked        | Blocked due to client IP address       | IP���������������������������             |
| ContentError   | Invalid format email                   | ���������������������������               |
| ExceedLimit    | Message size exceeded the limit(5.2.3) | ���������������������������               |
| Expired        | Delivery time expired                  | ������������������                     |
| Feedback       | Bounced for a complaint of the message | ���������������������������������������������   |
| Filtered       | Rejected after DATA command            | DATA������������������������������������     |
| HasMoved       | Destination mail addrees has moved     | ������������������������������������������     |
| HostUnknown    | Unknown destination host name          | ������������������������������������         |
| MailboxFull    | Recipient's mailbox is full            | ������������������������������             |
| MailerError    | Mailer program error                   | ������������������������������������         |
| MesgTooBig     | Message size is too big(5.3.4)         | ���������������������������               |
| NetworkError   | Network error: DNS or routing          | DNS���������������������������������������    |
| SpamDetected   | Detected a message as spam             | ���������������������������������������������   |
| NotAccept      | Destinaion does not accept any message | ������������������������������������������������ |
| OnHold         | Deciding the bounce reason is on hold  | ���������������������������������           |
| Rejected       | Rejected due to envelope from address  | ������������������From������������������     |
| NoRelaying     | Relay access denied                    | ������������������                     |
| SecurityError  | Virus detected or authentication error | ������������������������������������������     |
| Suspend        | Recipient's account is suspended       | ���������������������������������������������   |
| SystemError    | Some error on the destination host     | ���������������������OS���������������������   |
| SystemFull     | Disk full on the destination host      | ���������������������������������������       |
| TooManyConn    | Connection rate limit exceeded         | ������������������������������             |
| UserUnknown    | Recipient's address does not exist     | ���������������������������������������������   |
| Vacation       | Auto replied message such as vacation  | ���������������������������(vacation������) |
|                | (implemented at v4.1.28)               | (v4.1.28������������)                |
| Undefined      | Could not decide the error reason      | ������������������������������������������     |

Sisimai���������������������25������������������������


Parsed data structure | ���������������������������
------------------------------------------
The following table shows a data structure(Sisimai::Data) of parsed bounce mail.
More details about data structure are available at available at 
[Sisimai ��� Data Structure of Sisimai::Data Object](http://libsisimai.org/data) page.

| Name           | Description                           | ������������                       |
|----------------|---------------------------------------|--------------------------------|
| action         | The value of Action: header           | Action:���������������              |
| addresser      | The From address                      | ������������������������               |
| alias          | Alias of the recipient                | ���������������������������������������     |
| destination    | The domain part of the "recipinet"    | "recipient"���������������������      |
| deliverystatus | Delivery Status(DSN)                  | ������������(DSN)������              |
| diagnosticcode | Error message                         | ������������������������               |
| diagnostictype | Error message type                    | ���������������������������������         |
| feedbacktype   | Feedback Type                         | Feedback-Type������������������      |
| lhost          | local host name(local MTA)            | ���������MTA���������������            |
| listid         | List-Id: header of each ML            | List-Id���������������              |
| messageid      | Message-Id: of the original message   | ���������������Message-Id           |
| reason         | Detected bounce reason                | ������������������������������������       |
| recipient      | Recipient address which bounced       | ������������������������������������������   |
| replycode      | SMTP Reply Code                       | SMTP���������������                 |
| rhost          | Remote host name(remote MTA)          | ���������MTA���������������            |
| senderdomain   | The domain part of the "addresser"    | "addresser"���������������������      |
| softbounce     | The bounce is soft bounce or not      | ������������������������������������������   |
| smtpagent      | MTA name(Sisimai::MTA::, MSP::)       | MTA���(Sisimai::MTA::,MSP::)    |
| smtpcommand    | The last SMTP command in the session  | ���������������������������SMTP������������ |
| subject        | Subject of the original message(UTF8) | ���������������Subject(UTF-8)       |
| timestamp      | Date: header in the original message  | ���������������Date                 |
| timezoneoffset | Time zone offset(seconds)             | ���������������������������             |
| token          | MD5 value of addresser and recipient  | ���������������������������������������     |

���������������������������������������������������������(Sisimai::Data)���������


Emails could not be parsed | ���������������������������
-----------------------------------------------
Bounce mails which could not be parsed is in eg/cannot-parse-yet directory. 
If you find any bounce email cannot be parsed using Sisimai, please add the
email into the directory and send Pull-Request to this repository.

������������������������������eg/cannot-parse-yet������������������������������������������������������
Sisimai������������������������������������������������������������������������������������������Pull-Request
���������������������������


Other Information | ������������������
================================

Related Sites | ���������������
--------------------------

* __http://libsisimai.org/__ | [Sisimai ��� A successor to bounceHammer, Library to parse error mails](http://libsisimai.org/)
* __GitHub__ | [github.com/azumakuniyuki/p5-Sisimai](https://github.com/azumakuniyuki/p5-Sisimai)

SEE ALSO | ���������������
---------------------
* [RFC3463 - Enhanced Mail System Status Codes](https://tools.ietf.org/html/rfc3463)
* [RFC3464 - An Extensible Message Format for Delivery Status Notifications](https://tools.ietf.org/html/rfc3464)
* [RFC3834 - Recommendations for Automatic Responses to Electronic Mail](https://tools.ietf.org/html/rfc3834)
* [RFC5321 - Simple Mail Transfer Protocol](https://tools.ietf.org/html/rfc5321)
* [RFC5322 - Internet Message Format](https://tools.ietf.org/html/rfc5322)

AUTHOR | ������
-------------
[@azumakuniyuki](https://twitter.com/azumakuniyuki)

COPYRIGHT | ���������
------------------
Copyright (C) 2014-2015 azumakuniyuki <perl.org@azumakuniyuki.org>,
All Rights Reserved.

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