Recursive AI

Parse email bounce delivery status in C#

OneMail is a free, open-source email library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

A delivery status notification (DSN) carries machine-readable results for each recipient. bounce.eml is a synthetic failed-delivery message in the download, shown below.

Terminal
dotnet add package RecursiveAI.OneMail

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using RecursiveAI.OneMail.Mime;
using RecursiveAI.OneMail.Mime.Reports;
 
var mail = MimeEntity.Parse(
    File.ReadAllBytes("bounce.eml"));
var dsn = MimeReport.Find(mail)
    ?.GetDeliveryStatus();
if (dsn is not null)
    foreach (var recipient in dsn.Recipients)
        Console.WriteLine(
            $"{recipient.Status}: {recipient.DiagnosticCode?.Value}");

Unzip the example, then dotnet run.

The snippet at the top prints:

Text
5.1.1: 550 5.1.1 No such mailbox

The full program

The download’s Program.cs also prints the reporting mail server and each recipient’s action.

C#
using RecursiveAI.OneMail.Mime;
using RecursiveAI.OneMail.Mime.Reports;
 
var message = MimeEntity.Parse(File.ReadAllBytes("bounce.eml"));
var report = MimeReport.Find(message);
var status = report?.GetDeliveryStatus();
if (status is null)
{
    Console.WriteLine("No delivery status report.");
    return;
}
Console.WriteLine($"Reporting MTA: {status.ReportingMta?.Value}");
foreach (var recipient in status.Recipients)
{
    Console.WriteLine($"{recipient.FinalRecipient?.Value}: {recipient.Action} {recipient.Status}");
    Console.WriteLine($"Diagnostic: {recipient.DiagnosticCode?.Value}");
}
Text
Reporting MTA: mail.example.org
missing@example.net: Failed 5.1.1
Diagnostic: 550 5.1.1 No such mailbox

If no delivery-status report is found, the full program prints No delivery status report.; malformed fields can yield null typed values and reported defects.

The input, bounce.eml, is a synthetic example included in the zip. It uses CRLF line endings.

EML
From: postmaster@example.org
To: sender@example.org
Subject: Delivery failure
MIME-Version: 1.0
Content-Type: multipart/report; report-type=delivery-status; boundary="dsn-example"
 
--dsn-example
Content-Type: text/plain; charset=utf-8
 
Delivery to missing@example.net failed.
--dsn-example
Content-Type: message/delivery-status
 
Reporting-MTA: dns; mail.example.org
 
Final-Recipient: rfc822; missing@example.net
Action: failed
Status: 5.1.1
Diagnostic-Code: smtp; 550 5.1.1 No such mailbox
 
--dsn-example--

Variations

Append this to the full program to collect field defects separately from report-structure defects:

C#
var defects = new List<RecursiveAI.OneMail.Mime.Reading.MimeDefect>();
var parsed = report!.GetDeliveryStatus(defects);
Console.WriteLine($"Report defects: {report!.Defects.Count}");
Console.WriteLine($"Field defects: {defects.Count}");
Console.WriteLine($"Recipients: {parsed?.Recipients.Count}");

Additional output:

Text
Report defects: 0
Field defects: 0
Recipients: 1

The short answer

Parse the EML with MimeEntity.Parse, find its report with MimeReport.Find, then call GetDeliveryStatus. Iterate Recipients rather than assuming the message has only one result. Each recipient exposes a final address, action, enhanced status code and diagnostic when present. The full example prints those fields from a synthetic failed-delivery notification.

The machine-readable part matters more than a subject containing “delivery failed.” It supplies structured per-message and per-recipient blocks. A text-only rejection notice may be readable to a person without containing a DSN that this API can return.

How do you parse a bounced email in C#?

Look for a multipart/report container and a delivery-status machine part. MimeReport.Find returns the first report, including when it is inside a nested message/rfc822. GetDeliveryStatus returns null when the report is another kind or has no machine part. Treat that as “no DSN found,” not “delivery succeeded.”

The sample has a human-readable text part and a message/delivery-status part. The latter begins with Reporting-MTA, followed by an empty line and a recipient block. The output shows one recipient, but real notifications can have more. Keep every block and associate its diagnostic with its own final recipient.

For applications processing several recipients, avoid flattening the notification into one Boolean. The report’s PerMessage fields describe the report as a whole; Recipients hold the separate outcomes. OneMail’s report reference documents the fields and the typed views.

Why did I get an email saying delivery status notification failure?

A DSN reports a delivery result. Under RFC 3464 section 2.3.3, Action identifies the result for the recipient: failed, delayed, delivered, relayed or expanded. A delay is not the same as a final failure. Read the action alongside the status and diagnostic rather than inferring the outcome from the message subject.

The example’s action is Failed and its status is 5.1.1. RFC 3463 section 3.2 describes X.1.1 as a bad destination mailbox address; the first digit 5 means permanent failure. Its SMTP diagnostic says the mailbox does not exist. Those are the notification’s claims about this delivery, not a live mailbox lookup performed by the parser.

The diagnostic has a type as well as text. In this example that type is smtp; preserve the type if you store diagnostics from multiple transports. The SMTP reply number and enhanced status code are related fields, not interchangeable strings.

How to check delivery status on email?

For a notification you have already received, inspect every recipient’s Action, Status and DiagnosticCode. Use the variation to collect typed field defects as well as structural report defects. A field that does not fit its expected type can remain available as raw text while its typed property is null. Retain the original report when investigating those cases.

The parser does not send a message, request a delivery report or poll a mail server. It also does not turn a delivery notification into a read receipt. OneMail exposes disposition notifications separately through GetDispositionNotification; delivery and disposition reports have different machine media types and meanings.

Large or malformed reports can be only partially parsed under the documented report limits. Inspect defects before assuming you have all recipient blocks. Absence of a DSN, absence of a typed status or absence of a diagnostic is missing evidence, not confirmation of delivery.

All onemail recipes