Sisimai: Mail Analyzing Interface

Data Structure of Sisimai::Fact

The rise() method of Sisimai class returns an array of Sisimai::Fact objects containing the decoded data. The legacy Sisimai::Data object has been deprecated in Sisimai 5.0.0.

In the Go version of Sisimai, the Rise() function in the libsisimai.org/sisimai package returns a pointer to a slice containing multiple sis.Fact structs. The returned object/struct has the following data structure:

Read More
A

Action (String)

The "action" field holds the value of the Action: field in the bounce email. This field is normalized during the decoding process and can have one of the following five values:


  • dalayed
  • delivered
  • expanded
  • failed
  • relayed
Action: failed

Addresser (Sisimai::Address)

The "addresser" field is a Sisimai::Address object created from the sender address (From) of the original email in the bounce email. If the Sisimai::Fact object is dumped to JSON format, it will hold the email address (String).

In the Go version of Sisimai, the sis.EmailAddress struct has field names that start with a capital letter. However, when converted to JSON format, all field names become lowercase.

  • user() - The local part of the address
  • host() - The domain part of the address
  • address() - Email address
  • verp() - Variable envelope return path
  • alias() - Alias of the address
  • name() - Display name (v4.22.1 or later)
  • comment() - Comment (v4.22.1 or later)
From: "Kijitora Cat" <kijitora@example.org>

Alias (String)

The "alias" field is the alias of the recipient address. If the Original-Recipient: field or the email address following "expanded from" is described in the bounce email, the value will be extracted from there. 

Original-Recipient: rfc822;kijitora@example.org
                
"|IFS=' ' && exec /usr/local/bin/procmail -f- || exit 75 #kijitora"
(expanded from: <kijitora@neko.example.edu>)
C

Catch (*) | Beginning with v4.19.0

The "catch" field holds the value returned by the hook method passed to the rise() method of Sisimai class. If no hook method is passed, it will be undef in Perl and nil in Ruby. The callback feature, hook method settings, and catch() method were added in Sisimai 4.19.0.

Callback, hook method, and catch() method are implemented at Sisimai 4.19.0.

The argument names and types of the callback feature were changed in Sisimai 5.0.0. For details, see the Callback feature page.

In the Go version of Sisimai, it returns an interface{} type, so please refer to it after appropriate type assertion.

D

DeliveryStatus (String)

The "deliverystatus" field holds the value of the Status: field in the bounce email. If there is no Status: field in the bounce email, the internal code such as "5.0.9XX" may be included. The format of this value is a string like "4.x.x", "5.x.x", or "2.x.x". 

Status: 5.0.0 (permanent failure)

Destination (String)

The "destination" field holds the domain part of the recipient address as its value. This value is the same as the value returned by the host() method of the recipient() accessor.

DiagnosticCode (String)

The "diagnosticcode" field holds the error message extracted from the Diagnostic-Code: field in the bounce email or from the body of the bounce email. The value of this field and the values of "diagnostictype", "action", "deliverystatus", "replycode", and "smtpcommand" are referenced by the Sisimai::Reason class to determine the bounce reason. 

Diagnostic-Code: SMTP; 554 5.4.6 Too many hops

DiagnosticType (String)

The "diagnostictype" field holds the first part of the Diagnostic-Code: field in the bounce email, such as SMTP or X-Unix. If there is no Diagnostic-Code: field, this value will be empty. 

Diagnostic-Code: X-Unix; 255
F

FeedbackType (String)

The "feedbacktype" field holds the value of the Feedback-Type: field in the bounce email, such as abuse, fraud, or opt-out. If the bounce email is not in ARF format or the "reason" value is not "feedback", this value will be empty. 

Content-Type: message/feedback-report

Feedback-Type: abuse
User-Agent: SMP-FBL
F

HardBounce (Boolean) | v5.0.0 or later

The "hardbounce" field, newly implemented in Sisimai 5.0.0, returns a boolean value (0 or 1 in Perl, true or false in Ruby) indicating whether the destination email address bounced for a reason that it can never be delivered again. Specifically, it returns true if the "reason" has the following values:

At the same time, "softbounce" was deprecated in Sisimai 5.0.0.

L

Lhost (String)

The "lhost" field holds the hostname or IP address of the MTA used for sending, extracted from the Reporting-MTA: field in the bounce email or from the Received: header. 

Reporting-MTA: dns; mx4.smtp.example.co.jp

ListID (String)

The "listid" field holds the value of the List-Id: header extracted from the original message included in the bounce email. If the bounce email is in a format that does not have an original message, this value will be empty. 

List-Id: General discussion list for Cats <neko-list.example.org>
M

MessageID (String)

The "messageid" field holds the value of the Message-Id: header of the original message included in the bounce email. If the bounce email does not have an original message, this value will be empty. 

Message-Id: <201310160515.r9G5FZh9018575@smtpgw.example.jp>
O

Origin (String)

The "origin" field holds the filename (including path) of the original message included in the bounce email. Specifically, this is the first argument passed to the rise() or dump() method of the Sisimai class. In the case of Maildir/, the value will be a string that combines the directory name of the first argument and the filename here. If read from standard input, the value will be <STDIN>; if read from a variable, the value will be <MEMORY>.

The "origin" field was implemented in v4.25.6.

R

Reason (String)

The "reason" field holds the bounce reason (the reason why the email delivery failed) detected by Sisimai. If the value is "undefined" or "onhold", it means that Sisimai could not determine the bounce reason. You can check the list of bounce reasons that Sisimai can detect on Bounce Reason List page. 

   ----- The following addresses had permanent fatal errors -----

    (reason: 550 5.1.1 Requested action not taken: mailbox unavailable)

   ----- Transcript of session follows -----
... while talking to inbound-smtp.us-west-2.amazonaws.com.:
>>> RCPT To:
<<< 550 5.1.1 Requested action not taken: mailbox unavailable
550 5.1.1 ... User unknown
>>> DATA
<<< 503 Error: need RCPT command

Recipient (Sisimai::Address)

The "recipient" field is a Sisimai::Address object created from the recipient address in the bounce email. This address is the one that could not be delivered. If a Sisimai::Fact object is dumped in JSON format, it will hold the email address (String).

In the Go version of Sisimai, the sis.EmailAddress struct has field names that start with a capital letter. However, when converted to JSON format, all field names become lowercase.

  • user() - The local part of the address
  • host() - The domain part of the address
  • address() - Email address
  • verp() - Variable envelope return path
  • alias() - Alias of the address
  • name() - Display name (v4.22.1 or later)
  • comment() - Comment (v4.22.1 or later)
Final-Recipient: RFC822; shironeko@example.ne.jp
                
X-Failed-Recipients: kijitora@example.ed.jp

ReplyCode (String)

The "replycode" field holds the SMTP response code extracted from the Diagnostic-Code: field or the bounce email body. The value range is "2xx", "4xx" to "5xx". 

----- The following addresses had permanent fatal errors -----

(reason: 550 5.1.1 ... User Unknown)

Rhost (String)

The "rhost" field holds the value of the Remote-MTA: field or the hostname or IP address of the remote MTA extracted from the Received: header in the bounce email. 

Remote-MTA: DNS; g5.example.net
S

SenderDomain (String)

The "senderdomain" field holds the domain part of the sender address of the original email. This value is the same as the value returned by the host() method of the addresser() accessor.

smtpagent (String)

The "smtpagent" field holds the name of the MTA module that determined the bounce reason. For example, if the value is "Sendmail", it means that the Sisimai::Lhost::Sendmail module performed the recipient address acquisition and bounce reason determination that resulted in an error.

smtpcommand (String)

The "smtpcommand" field holds the SMTP command that is thought to have been issued last in the SMTP session, extracted from the Diagnostic-Code: field or the bounce email body. If there is no record of the SMTP command in the bounce email, this value will be empty.

  • HELO
  • EHLO
  • MAIL
  • RCPT
  • DATA
: host mx1.example.go.jp[192.0.2.127] said: 550 5.1.6 recipient
no longer on server: kijitora@example.go.jp (in reply to RCPT TO command)

softbounce (Integer)| deprecated in v5.0.0

The "softbounce" value indicates whether the bounce reason is a soft bounce (retryable) or a hard bounce. This field was added in Sisimai 4.1.28. The possible values are as follows: 1 for soft bounce, 0 for hard bounce, and -1 if it cannot be determined.

This field was deprecated in Sisimai v5.0.0. It can still be used for compatibility reasons up to v5.1.0, but please use "hardbounce" instead.

  • 1 = Soft bounce
  • 0 = Hard bounce
  • -1 = Sisimai could not decide

Subject (String)

The "subject" field holds the value of the Subject: header of the original email. If the bounce email does not include the original message, this value will be empty. If the Subject: of the original message contains multibyte characters encoded in MIME (such as Japanese or other languages that use non-ASCII characters), Sisimai treats it as UTF-8.

T

Timestamp (Sisimai::Time)

The "timestamp" field is a Sisimai::Time object (a subclass of Time::Piece in Perl and a subclass of DateTime in Ruby) that holds the date and time of the bounce. When a Sisimai::Fact object is dumped to JSON format, it is converted to a 32-bit integer machine time. 

Arrival-Date: Thu, 29 Apr 2009 23:45:33 +0900

TimezoneOffset (String)

The "timezoneoffset" field holds the time zone of the bounced date and time as a string like "+0900" or "-0200". If Sisimai failed to determine the time zone from the timestamp in the bounce email, this value will be "+0000". 

Arrival-Date: Mon, 16 Dec 2019 22:00:18 +0100 (CET)
Date: Thu, 29 Apr 2018 23:34:45 +0900 (JST)

Token (String)

The "token" is a unique identifier for a bounce record that is generated based on the sender address, recipient address, and time of the original email. The value is an MD5 hash value generated by the token() method of the Sisimai::String class. To get the token value on the command line, you can execute a command like the following: 

% printf "\x02%s\x1e%s\x1e%d\x03" sender@example.jp recipient@example.org `date '+%s'` | md5
714d72dfd972242ad04f8053267e7365