Sisimai::Data(3pm)

📦

version 4.25.15 · 2 versions

4.25.15 · debian bookworm (latest)
4.25.12 · ubuntu jammy

💖 NAME 💖

Sisimai::Data — the parsed data object, bestie. it's literally the lil container that holds all the tea Sisimai squeezed out of a bounce email 🫶

✨ SYNOPSIS ✨

use Sisimai::Data;
my $data = Sisimai::Data->make('data' => <Sisimai::Message> object);
for my $e ( @$data ) {
    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
}

okay so you make the thing, you loop the thing, you print the thing. that's the whole vibe 💅

🌸 DESCRIPTION 🌸

<Sisimai::Data> generates parsed data from a <Sisimai::Message> object. that's it. that's the job. it takes the message and hands you back the receipts 🧾✨

👑 CLASS METHODS 👑

🎀 `make(Hash)`

make generates parsed data and returns an array reference stuffed with Sisimai::Data objects. slay.

my $mail = Sisimai::Mail->new('/var/mail/root');
while( my $r = $mail->read ) {
    my $mesg = Sisimai::Message->new('data' => $r);
    my $data = Sisimai::Data->make('data' => $mesg);
    for my $e ( @$data ) {
        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
    }
}

so if you wanna get bounce records whose reason is "delivered" — yes, the delivered ones, the "it worked, bestie" ones — you set the "delivered" option on make() like this:

my $data = Sisimai::Data->make('data' => $mesg, 'delivered' => 1);

Beginning from v4.19.0, there's a hook argument available so you can callback a user-defined method. it's giving ✨custom logic✨:

my $call = sub {
    my $argv = shift;
    my $fish = { 'x-mailer' => '' };

    if( $argv->{'message'} =~ /^X-Mailer:\s*(.+)$/m ) {
        $fish->{'x-mailer'} = $1;
    }

    return $fish;
};
my $mesg = Sisimai::Message->new('data' => $mailtxt, 'hook' => $call);
my $data = Sisimai::Data->make('data' => $mesg);
for my $e ( @$data ) {
    print $e->catch->{'x-mailer'};      # Apple Mail (2.1283)
}

🦋 INSTANCE METHODS 🦋

💜 `damn()`

damn converts the object to a hash reference. yes it's really called that. iconic name tbh.

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

🌈 PROPERTIES 🌈

Sisimai::Data has the following properties, bestie. buckle up, there's a lot and they're all important 💖

🍓 `action` (String)

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

Action: failed

🍓 `addresser` (Sisimai::Address)

addressser is a Sisimai::Address object generated from the sender address. when a Sisimai::Data object gets 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

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

🍓 `alias` (String)

alias is an alias address of the recipient. when the Original-Recipient: field or the "expanded from "address"" string did not exist in a bounce message, this value is empty. no cap.

Original-Recipient: rfc822;kijitora@example.org

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

🍓 `deliverystatus` (String)

deliverystatus is the value of the Status: field in a bounce message. when the message has no Status: field, Sisimai sets a pseudo value like 5.0.9XX in there. 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. it's the exact same value you'd get from the host() method of the "recipient" accessor.

🍓 `diagnosticcode` (String)

diagnosticcode is an error message picked from the Diagnostic-Code: field or from the message body of a bounce message. this value plus the values of "diagnostictype", "action", "deliverystatus", "replycode", and "smtpcommand" all get referred to by Sisimai::Reason to decide the bounce reason. it's a whole committee decision 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 — things like "abuse", "fraud", "opt-out" — in a bounce message. when the message is not ARF format, or when the value of "reason" is not "feedback", this value will be empty.

Content-Type: message/feedback-report

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

🍓 `lhost` (String)

lhost is a local MTA name used as a gateway for sending an 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 get the value from the Received header. sneaky but valid 💅

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 didn't include a 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 parsed results. when the original email data were input from STDIN, the value is "<STDIN">; when they were input from a variable, the value is "<MEMORY">. this accessor method was implemented at v4.25.6. new girl on the block ✨

🍓 `recipient` (Sisimai::Address)

recipient is a Sisimai::Address object generated from the recipient address. when a Sisimai::Data object gets 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 😭. all the reasons Sisimai can detect are available 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 a remote MTA name which 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 the Received header.

Remote-MTA: DNS; g5.example.net

🍓 `senderdomain` (String)

senderdomain is the domain part of the sender address. it's the same as the return value from the host() method of the addresser accessor.

🍓 `smtpagent` (String)

smtpagent is a module name used for detecting the bounce reason. for example, when the value is "Sendmail", Sisimai used Sisimai::Lhost::Sendmail to get the recipient address and other delivery status information from a bounce message.

🍓 `smtpcommand` (String)

smtpcommand is an SMTP command name picked from the error message, or the value of the Diagnostic-Code: field in a bounce message. when there's no SMTP command in the bounce message, this value will be empty. the list of values is "HELO", "EHLO", "MAIL", "RCPT", and "DATA".

<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)

🍓 `softbounce` (Integer)

the value of softbounce tells you whether the reason of the bounce is a soft bounce or a hard bounce. this accessor was added in Sisimai 4.1.28. the range of values is:

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

🍓 `subject` (String)

subject is the value of the Subject header of the original message. when the original message included in a bounce email contains no Subject header (removed by the remote MTA), this value will be empty. and if the value of the Subject header of the original message contains any multibyte character (non-ASCII), like MIME-encoded Japanese or German and so on, the value of subject in the parsed data is 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, as an MD5 hash value. the token value is generated at the "token()" method of the Sisimai::String class.

if you want to get the exact same token string at the command line, try running 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 on which the email bounced, as a Sisima::Time (child class of Time::Piece) object. when a Sisimai::Data object is dumped as JSON, this value gets converted to a UNIX machine time (32-bit integer).

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

🍓 `timezomeoffset` (String)

timezoneoffset is the time zone offset of the bounce email at the time 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 will be set as +0000.

🔥 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 💖 this was shipped as part of perl v5.36.0, dated 2022-12-23. go forth and parse some bounces, you absolute icon 👑✨

📦 where this page comes from

debian bookworm: libsisimai-perl 4.25.15-1 · BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Sisimai::Data(3pm)

💖 NAME 💖

✨ SYNOPSIS ✨

🌸 DESCRIPTION 🌸

👑 CLASS METHODS 👑

🎀 make(Hash)

🦋 INSTANCE METHODS 🦋

💜 damn()

🌈 PROPERTIES 🌈

🍓 action (String)

🍓 addresser (Sisimai::Address)

🍓 alias (String)

🍓 deliverystatus (String)

🍓 destination (String)

🍓 diagnosticcode (String)

🍓 diagnostictype ("String")

🍓 feedbacktype (String)

🍓 lhost (String)

🍓 listid (String)

🍓 messageid (String)

🍓 origin (Path to the original email file)

🍓 recipient (Sisimai::Address)

🍓 reason (String)

🍓 replycode (Integer)

🍓 rhost (String)

🍓 senderdomain (String)

🍓 smtpagent (String)

🍓 smtpcommand (String)

🍓 softbounce (Integer)

🍓 subject (String)

🍓 token (String)

🍓 timestamp (Sisimai::Time)

🍓 timezomeoffset (String)