Sisimai: Mail Analyzing Interface

Sisimai::Factのデータ構造

Sisimaiのrise()メソッドは解析したデータを Sisimai::Factオブジェクトを複数個含む配列にして返します。 Sisimai 5.0.0で従来のSisimai::Data オブジェクトは廃止になりました。

Go版Sisimaiではlibsisimai.org/sisimaiパッケージの Rise()関数が sis.Fact 構造体を複数個含むスライスへのポインターを返します。 返ってきたオブジェクト/構造体は以下のようなデータ構造になっています。

詳しく
A

Action (String)

"action" はバウンスメール内のAction: フィールドの値を保持します。この項目は、解析の過程で表記の揺れ(deliverable, failureなど)は修正され、 次の五つの値となります。


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

Addresser (Sisimai::Address)

"addresser" はバウンスメール内にある元メールの 発信者アドレス(From)から作られるSisimai::Address オブジェクトです。 Sisimai::FactオブジェクトをJSON形式にダンプした場合はメールアドレス (文字列)を保持します。

Go版Sisimaiでは sis.EmailAddress 構造体で、それぞれのフィールド名は大文字から始まりますが、JSON形式に変換した場合は 全て小文字のフィールド名になります。

  • user() - メールアドレスの"@"の左側
  • host() - メールアドレスの"@"の右側
  • address() - メールアドレス
  • verp() - VERP形式のReturn-Path
  • alias() - エイリアス
  • name() - メールヘッダの表示名(v4.22.1以降)
  • comment() - コメント(v4.22.1以降)
From: "Kijitora Cat" <kijitora@example.org>

Alias (String)

"alias" は受信者アドレスのエイリアスです。 バウンスメール内のOriginal-Recipient: フィールドや "expanded from"に続くメールアドレスが記述されていたら、 そこから値を取り出します。 

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

Catch (*) | v4.19.0以降

"catch" はSisimaiのrise()メソッドに渡した フックメソッドが返した値を保持します。フックメソッドを渡さなかった場合は、Perlなら undef、Rubyならnilとなります。 コールバック機能とフックメソッドの設定、catch() メソッドはSisimai 4.19.0で追加されました。

Sisimai 5.0.0でコールバック機能の引数名と引数の型が変更になりました。詳細は Callback feature をご覧下さい。

Go版Sisimaiの場合はinterface{}型で返しますので 適切な型アサーションを経て参照してください。

D

DeliveryStatus (String)

"deliverystatus"はバウンスメール内の Status: フィールドの値を保持します。もしもバウンスメールに Status: フィールドが無かった場合は "5.0.9XX"のような内部コードが 入る事があります。この値の形式は "4.x.x" か "5.x.x" あるいは "2.x.x" のような文字列となります。 

Status: 5.0.0 (permanent failure)

Destination (String)

"destination" は受信者アドレスのドメインパートを値として保持します。 この値は recipient() アクセサのhost()メソッドが返す値と同じです。

DiagnosticCode (String)

"diagnosticcode" はバウンスメール内のDiagnostic-Code: フィールドまたはバウンスメールの本文から取り出したエラーメッセージを保持します。

この値と "diagnostictype", "action", "deliverystatus", "replycode", "smtpcommand" の各値はバウンス理由を決定する為に Sisimai::Reasonクラスから参照されます。 

Diagnostic-Code: SMTP; 554 5.4.6 Too many hops

DiagnosticType (String)

"diagnostictype"はバウンスメール内のDiagnostic-Code: フィールドの先頭部分、SMTP や X-Unix のような値を保持します。 Diagnostic-Code:フィールドが無い場合、この値は空になります。 

Diagnostic-Code: X-Unix; 255
F

FeedbackType (String)

"feedbacktype" はバウンスメール内のFeedback-Type: フィールドの値で、abuse, fraud, opt-outのような値を保持します。 バウンスメールがARFフォーマットではない、または"reason" の値が "feedback"ではない場合、この値は空になります。 

Content-Type: message/feedback-report

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

HardBounce (Boolean) | v5.0.0以降

Sisimai 5.0.0で新たに実装された"hardbounce"は、 宛先メールアドレスが二度と配信できない理由でバウンスしたかどうかを示す真偽値 (Perl版は0か1, Ruby版はtrueかfalse) を返します。

具体的には"reason"が次の値である 場合に真となります。

同時に"softbounce"はSisimai 5.0.0で廃止となりました。

L

Lhost (String)

"lhost" はバウンスメール内の Reporting-MTA: フィールドの値または Receivedヘッダから取り出した 送信に使われたMTAのホスト名またはIPアドレスを保持します。 

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

ListID (String)

"listid"はバウンスメールに含まれる元メッセージから List-Id:ヘッダの値を取り出したものを保持します。 元メッセージが無い形式のバウンスメールの場合、この値は空になります。 

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

MessageID (String)

"messageid"はバウンスメールに含まれる元メッセージの Message-Id:ヘッダーの値を保持します。 バウンスメールに元メッセージが無い場合、この値は空になります。 

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

Origin (String)

"origin"はバウンスメールに含まれる元メッセージの ファイル名(パスを含む)を保持します。具体的にはSisimaiクラスのrise() メソッドやdump()に渡した第一引数です。Maildir/の場合は第一引数のディレクトリ名に ここのファイル名が結合された文字列が入ります。 標準入力から読み込んだ場合は<STDIN>が、 変数から読み込んだ場合は<MEMORY>が、それぞれ値となります。

"origin"はv4.25.6で実装されました。

R

Reason (String)

"reason"はSisimaiが検出したバウンス理由 (メールが配信エラーになった理由)を保持します。 値が"undefined"か "onhold" の時はSisimaiがバウンス理由を特定出来なかった事を意味します。

Sisimaiが検出出来るバウンス理由の一覧は バウンス理由の一覧のページで確認出来ます。 

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

"recipient"はバウンスメール内にある受信者アドレスから 作られるSisimai::Addressオブジェクトです。このアドレスがまさに配信出来なかった アドレスとなります。Sisimai::FactオブジェクトをJSON形式にダンプした場合は メールアドレス(文字列)を保持します。

Go版Sisimaiでは sis.EmailAddress 構造体で、それぞれのフィールド名は大文字から始まりますが、JSON形式に変換した場合は 全て小文字のフィールド名になります。

  • user() - メールアドレスの"@"の左側
  • host() - メールアドレスの"@"の右側
  • address() - メールアドレス
  • verp() - VERP形式のReturn-Path:
  • alias() - エイリアス
  • name() - メールヘッダの表示名(v4.22.1以降)
  • comment() - コメント(v4.22.1以降)
Final-Recipient: RFC822; shironeko@example.ne.jp
                
X-Failed-Recipients: kijitora@example.ed.jp

ReplyCode (String)

"replycode"はバウンスメール内のDiagnostic-Code: フィールドやバウンスメール本文から取り出したSMTP応答コードを保持します。 値の範囲は"2xx", "4xx"〜 "5xx"となります。 

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

(reason: 550 5.1.1 ... User Unknown)

Rhost (String)

"rhost"はバウンスメール内にある Remote-MTA: フィールドの値または Received: ヘッダから取り出した相手側MTAのホスト名か IPアドレスを保持します。 

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

SenderDomain (String)

"senderdomain"は元メールの発信者アドレスのドメイン部分を保持します。 この値はaddresser()アクセサのhost()メソッドが返す値と同じです。

smtpagent (String)

"smtpagent"はバウンス理由を特定したMTAモジュール名を保持します。 例えば値が"Sendmail"であればSisimai::Lhost::Sendmailモジュールが エラーとなった受信者アドレス取得やバウンス理由特定を行った事を意味します。

smtpcommand (String)

"smtpcommand" はバウンスメールのDiagnostic-Code: フィールドまたはバウンスメール本文から取り出した、SMTPセッションで最後に発行したと 思われるSMTPコマンドを保持します。 バウンスメール内にSMTPコマンドの記録が無い場合、この値は空になります。

  • 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) | v5.0.0で廃止

"softbounce"の値はバウンス理由がソフトバウンス(再試行で送信可能)か ハードバウンスであるかを示します。この項目はSisimai 4.1.28で追加されました。 とりうる値は上記の通り、1がソフトバウンス、 0がハードバウンス、-1 がどちらか判断出来なかった、となります。

この項目はv5.0.0で廃止になりました。 v5.1.0までは互換性の為、 使用可能ですが、"hardbounce"を使ってください。

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

Subject (String)

"subject"は元メールの Subject: ヘッダの値を保持します。バウンスメールに元メッセージが含まれていない場合、この値は空になります。

もしも元メッセージのSubject:がMIMEエンコードされた マルチバイト文字を含むもの(日本語など非ASCII文字を使用する言語)である場合、 SisimaiはUTF-8として扱います。

T

Timestamp (Sisimai::Time)

"timestamp"はバウンスした日時を保持するSisima::Time (PerlではTime::Pieceの子クラス, RubyではDateTimeの子クラス) オブジェクトです。Sisimai::FactオブジェクトをJSON形式にダンプした場合、 32ビット整数のマシンタイムに変換されます。 

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

TimezoneOffset (String)

"timezoneoffset"はバウンスした日時のタイムゾーンを "+0900"や "-0200" のような文字列で保持します。 Sisimaiがバウンスメール内のタイムスタンプからタイムゾーンの特定に失敗した場合、 この値は "+0000" となります。 

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

Token (String)

"token"は元メールの発信者アドレス、受信者アドレス、 時刻を元に生成されるバウンス記録の一意な識別子です。 値はMD5のハッシュ値でSisimai::Stringクラスのtoken() メソッドで生成されます。 もしも"token"の値をコマンドラインで得るなら、下記 のようなコマンドを実行してください。 

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