Sisimai::Fact(3pm)

📦

version 5.7.0 · 4 versions

🌸 NAME 🌸

Sisimai::Fact — the decoded data object, bestie 💖 (this is the Sisimai::Fact(3pm) page, User Contributed Perl Documentation, if you were wondering where you wandered into)

✨ SYNOPSIS ✨

use Sisimai::Fact;
my $args = {'data' => 'entire-email-text-including-all-the-headers'};
my $fact = Sisimai::Fact->rise($args);
for my $e ( @$fact ) {
    print $e->reason;               # userunknown, mailboxfull, and so on.
    print $e->recipient->address;   # (Sisimai::Address) envelope recipient address
    print $e->bonced->ymd           # (Sisimai::Time) Date of bounce
}

🦋 DESCRIPTION 🦋

okay so, "Sisimai::Fact" takes a "Sisimai::Message" object and generates a decoded bounce email data structure out of it. that's literally the whole job. slay. 💅

👑 CLASS METHODS 👑

🌈 `rise(Hash)`

the rise() method generates decoded data and hands you back an array reference full of "Sisimai::Fact" objects. iconic.

my $mail = Sisimai::Mail->new('/var/mail/root');
while( my $r = $mail->read ) {
    my $fact = Sisimai::Fact->make('data' => $r);
    for my $e ( @$fact ) {
        print $e->reason;               # userunknown, mailboxfull, and so on.
        print $e->recipient->address;   # (Sisimai::Address) envelope recipient address
        print $e->timestamp->ymd        # (Sisimai::Time) Date of the email bounce
    }
}

and if you want bounce records where the reason is "delivered" 🫶 you set the "delivered" option on the rise() method, like this:

my $fact = Sisimai::Fact->rise('data' => $r, 'delivered' => 1);

💜 `token(sender, recipient)`

the token() method makes a "token": it's a unique string generated from the envelope sender address plus the envelope recipient address. one of a kind, no dupe energy. ✨

my $s = 'envelope-sender@example.jp';
my $r = 'envelope-recipient@example.org';

print Sisimai::String->token($s, $r);    # 2d635de42a44c54b291dda00a93ac27b

🎀 INSTANCE METHODS 🎀

🍓 `damn()`

the "damn" method converts the object into a hash reference. (yes, that's the name. we love her for it.)

my $hash = $self->damn;
print $hash->{'recipient'}; # user@example.jp
print $hash->{'timestamp'}; # 1393940000

💖 PROPERTIES 💖

"Sisimai::Fact" has the following properties, bestie — get comfy, this list is long and every single one matters:

⭐ `action` (String)

"action" is the value of the "Action:" field in a bounce email message — things like "failed" or "delayed".

Action: failed

⭐ `addresser` (Sisimai::Address)

"addressser" is a Sisimai::Address object generated from the sender address. when the "Sisimai::Fact" object gets dumped as JSON, this value gets converted into an email address. the "Sisimai::Address" object has these accessors:

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

From: "Kijitora Cat" <kijitora@example.org>

⭐ `alias` (String)

"alias" is an alias address of the recipient. when there's no "Original-Recipient:" field and no "expanded from "address"" string in the bounce message, this value is empty. lowkey sad but that's the rule. 😭

Original-Recipient: rfc822;kijitora@example.org

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

⭐ `command` (String)

"command" is the SMTP command name, picked out of the error message or the value of the "Diagnostic-Code:" field in a bounce message. if there's no SMTP command in the bounce message, this value will be empty. the possible values are "HELO", "EHLO", "MAIL", "RCPT", "DATA", and "CONN". heads up: until v5.2.0 this accessor was called "smtpcommand". 🫶

<kijitora@example.go.jp>: 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)

⭐ `decodedby` (String)

"decodedby" is the module name used to decode a bounce message. for example, when the value is "Sendmail", Sisimai used Sisimai::Lhost::Sendmail to decode the bounce message, to find the recipient address, and to collect error messages so it could decide on a bounce reason. and yep: until v5.2.0, this accessor was named "smtpagent".

⭐ `deliverystatus` (String)

"deliverystatus" is the value of the "Status:" field in a bounce message. when the message has no "Status:" field, Sisimai drops in a pseudo value like "5.0.9XX" instead. the range of values is only "4.x.x" or "5.x.x".

Status: 5.0.0 (permanent failure)

⭐ `destination` (String)

"destination" is the domain part of the recipient address. this value is the same as what you get back from the host() method of the "recipient" accessor. same energy, different door. 🚪

⭐ `diagnosticcode` (String)

"diagnosticcode" is an error message picked from the "Diagnostic-Code:" field or the message body of a bounce message. this value, plus the values of "diagnostictype", "action", "deliverystatus", "replycode", and "command", all get referred to by Sisimai::Reason when deciding the bounce reason. squad effort fr fr. 👑

Diagnostic-Code: SMTP; 554 5.4.6 Too many hops

⭐ `diagnostictype` ("String")

"diagnostictype" is a type like "SMTP" or "X-Unix", picked from the "Diagnostic-Code:" field in a bounce message. when there's no "Diagnostic-Code:" field in the bounce message, this value will be empty.

Diagnostic-Code: X-Unix; 255

⭐ `feedbacktype` (String)

"feedbacktype" is the value of the "Feedback-Type:" field — like "abuse", "fraud", "opt-out" — in a bounce message. when the message isn't ARF format, or when the value of "reason" isn't "feedback", this value will be empty.

Content-Type: message/feedback-report

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

⭐ `hardbounce` (Integer)

the value of "hardbounce" tells you whether the bounce reason is a hard bounce or not. this accessor was added in Sisimai 5.0.0. the possible values are:

1 = Hard bounce
0 = Not a hard bounce

⭐ `lhost` (String)

"lhost" is the local MTA name used as the gateway for sending the email message, or the value of the "Reporting-MTA:" field in a bounce message. when there's no "Reporting-MTA:" field in the bounce message, Sisimai tries to grab the value from "Received:" headers. detective mode 🔎

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

⭐ `listid` (String)

"listid" is the value of the "List-Id:" header of the original message. when there's no "List-Id:" field in the original message, or the bounce message didn't include the original message, this value will be empty.

List-Id: Mailman mailing list management users

⭐ `messageid` (String)

"messageid" is the value of the "Message-Id:" header of the original message. when the original message had no "Message-Id:" header, or the bounce message didn't include the original message, this value will be empty.

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

⭐ `origin` (Path to the original email file)

"origin" is the path to the original email file of the decoded results. when the original email data came in from STDIN, the value is "<STDIN">; when it came in from a variable, the value is "<MEMORY">. this accessor method was implemented at v4.25.6. 💫

⭐ `recipient` (Sisimai::Address)

"recipient" is a Sisimai::Address object generated from the recipient address. when the "Sisimai::Fact" object is dumped as JSON, this value gets converted to an email address. the "Sisimai::Address" object has these accessors:

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

Final-Recipient: RFC822; shironeko@example.ne.jp
X-Failed-Recipients: kijitora@example.ed.jp

⭐ `reason` (String)

"reason" is the value of the bounce reason Sisimai detected. when this value is "undefined" or "onhold", it means Sisimai could not decide the reason — no cap, it just couldn't. all the reasons Sisimai can detect live over at Sisimai::Reason or on the web site <https://libsisimai.org/en/reason/>.

⭐ `replycode` (Integer)

"replycode" is the value of the SMTP reply code, picked from the error message or the value of the "Diagnostic-Code:" field in a bounce message. the range of values is only "4xx" or "5xx".

       ----- The following addresses had permanent fatal errors -----
    <userunknown@libsisimai.org>
        (reason: 550 5.1.1 <userunknown@libsisimai.org>... User Unknown)

⭐ `rhost` (String)

"rhost" is the remote MTA name that rejected the message you sent, or the value of the "Remote-MTA:" field in a bounce message. when there's no "Remote-MTA:" field in the bounce message, Sisimai tries to get the value from "Received:" headers. again with the detective work 🕵️

Remote-MTA: DNS; g5.example.net

⭐ `senderdomain` (String)

"senderdomain" is the domain part of the sender address. this value is the same as what comes back from the host() method of the addresser accessor.

⭐ `subject` (String)

"subject" is the value of the "Subject:" header of the original message. when the original message included in the bounce email has no "Subject:" header (because the remote MTA removed it), this value will be empty. and if the "Subject:" header value of the original message contains any multibyte character (a non-ASCII character) — like MIME-encoded Japanese, German, and so on — the value of "subject" in the decoded data gets encoded with UTF-8 again. glow-up ✨

⭐ `token` (String)

"token" is an identifier of each email-bounce. the token string is created from the sender email address ("addresser") and the recipient email address ("recipient") and the machine time of the date in a bounce message, all mashed into an MD5 hash value. the token value is generated at the token() method of the Sisimai::String class.

if you want the same token string at the command line, go ahead and run this:

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

⭐ `timestamp` (Sisimai::Time)

"timestamp" is the date the email bounced, as a Sisima::Time object (a child class of "Time::Piece"). when the "Sisimai::Fact" object is dumped as JSON, this value gets converted into a UNIX machine time (32-bit integer).

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

⭐ `timezomeoffset` (String)

"timezoneoffset" is a time zone offset of a bounce email, from when the email bounced. the format of this value is a String like +0900, -0200. if Sisimai failed to get a value for the time zone offset, this value is set as +0000.

⭐ `toxic` (Integer)

"toxic" is a flag for whether the recipient address should be permanently excluded from the list or not. 💀🚫

🌈 SEE ALSO 🌈

<https://libsisimai.org/en/data/>

💜 AUTHOR 💜

azumakuniyuki

🌸 COPYRIGHT 🌸

🫶 LICENSE 🫶

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

and that's the whole page, bestie 🎀 go forth and decode those bounces, you've got this — perl v5.40.1, 2026-07-05, Sisimai::Fact(3pm), mwah 💖✨

📦 where this page comes from

ubuntu stonking: libsisimai-perl 5.7.0-1 · BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

Sisimai::Fact(3pm)

🌸 NAME 🌸

✨ SYNOPSIS ✨

🦋 DESCRIPTION 🦋

👑 CLASS METHODS 👑

🌈 rise(Hash)

💜 token(sender, recipient)

🎀 INSTANCE METHODS 🎀

🍓 damn()

💖 PROPERTIES 💖

⭐ action (String)

⭐ addresser (Sisimai::Address)

⭐ alias (String)

⭐ command (String)

⭐ decodedby (String)

⭐ deliverystatus (String)

⭐ destination (String)

⭐ diagnosticcode (String)

⭐ diagnostictype ("String")

⭐ feedbacktype (String)

⭐ hardbounce (Integer)

⭐ lhost (String)

⭐ listid (String)

⭐ messageid (String)

⭐ origin (Path to the original email file)

⭐ recipient (Sisimai::Address)

⭐ reason (String)

⭐ replycode (Integer)

⭐ rhost (String)

⭐ senderdomain (String)

⭐ subject (String)

⭐ token (String)

⭐ timestamp (Sisimai::Time)

⭐ timezomeoffset (String)

⭐ toxic (Integer)