parse¶

  my $bounce = Mail::DeliveryStatus::BounceParser->parse($message, \%arg);

OPTIONS. If you pass BounceParser->new(..., {log=>sub { ... }}) That will be used as a logging callback. If $message is undefined, will parse STDIN.

NON-BOUNCES. If the message is recognizably a vacation autoresponse, or is a report of a transient nonfatal error, or a spam or virus autoresponse, you'll still get back a $bounce, but its "$bounce->is_bounce()" will return false.

It is possible that some bounces are not really bounces; such as anything that appears to have a 2XX status code. To include such non-bounces in the reports, pass the option {report_non_bounces=>1}.

For historical reasons, "new" is an alias for the "parse" method.

log¶

  $bounce->log($messages);

If a logging callback has been given, the message will be passed to it.

is_bounce¶

  if ($bounce->is_bounce) { ... }

This method returns true if the bounce parser thought the message was a bounce, and false otherwise.

reports¶

Each $report returned by $bounce->reports() is basically a Mail::Header object with a few modifications. It includes the email address bouncing, and the reason for the bounce.

Consider an RFC1892 error report of the form

 Reporting-MTA: dns; hydrant.pobox.com
 Arrival-Date: Fri,  4 Oct 2002 16:49:32 -0400 (EDT)
 Final-Recipient: rfc822; bogus3@dumbo.pobox.com
 Action: failed
 Status: 5.0.0
 Diagnostic-Code: X-Postfix; host dumbo.pobox.com[208.210.125.24] said: 550
  <bogus3@dumbo.pobox.com>: Nonexistent Mailbox

Each "header" above is available through the usual get() mechanism.

  print $report->get('reporting_mta');   # 'some.host.com'
  print $report->get('arrival-date');    # 'Fri,  4 Oct 2002 16:49:32 -0400 (EDT)'
  print $report->get('final-recipient'); # 'rfc822; bogus3@dumbo.pobox.com'
  print $report->get('action');          # "failed"
  print $report->get('status');          # "5.0.0"
  print $report->get('diagnostic-code'); # X-Postfix; ...
  # BounceParser also inserts a few interpretations of its own:
  print $report->get('email');           # 'bogus3@dumbo.pobox.com'
  print $report->get('std_reason');      # 'user_unknown'
  print $report->get('reason');          # host [199.248.185.2] said: 550 5.1.1 unknown or illegal user: somebody@uss.com
  print $report->get('host');            # dumbo.pobox.com
  print $report->get('smtp_code');       # 550
  print $report->get('raw') ||           # the original unstructured text
        $report->as_string;              # the original   structured text

Probably the two most useful fields are "email" and "std_reason", the standardized reason. At this time BounceParser returns the following standardized reasons:

  user_unknown
  over_quota
  user_disabled
  domain_error
  spam
  message_too_large
  unknown
  no_problemo

The "spam" standard reason indicates that the message bounced because the recipient considered it spam.

(no_problemo will only appear if you set {report_non_bounces=>1})

If the bounce message is not structured according to RFC1892, BounceParser will still try to return as much information as it can; in particular, you can count on "email" and "std_reason" to be present.

addresses¶

Returns a list of the addresses which appear to be bouncing. Each member of the list is an email address string of the form 'foo@bar.com'.

orig_message_id¶

If possible, returns the message-id of the original message as a string.

orig_message¶

If the original message was included in the bounce, it'll be available here as a message/rfc822 MIME entity.

  my $orig_message    = $bounce->orig_message;

orig_header¶

If only the original headers were returned in the text/rfc822-headers chunk, they'll be available here as a Mail::Header entity.

orig_text¶

If the bounce message was poorly structured, the above two methods won't return anything --- instead, you get back a block of text that may or may not approximate the original message. No guarantees. Good luck.

TODO¶

Provide some translation of the SMTP and DSN error codes into English. Review RFC1891 and RFC1893.