Recursive AI

Read Maildir messages and flags in C#

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

Maildir stores one email per file. Use inbox from the zip.

Terminal
dotnet add package RecursiveAI.OneMail

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

C#
using RecursiveAI.OneMail;
using RecursiveAI.OneMail.Stores;
using RecursiveAI.OneMail.Stores.Maildir;
PhysicalStoreFileSystem fs = new("inbox");
var store = new MaildirStore(fs);
foreach (var item in store.Enumerate())
{
    var path = $"inbox/{item.Path}";
    var bytes = File.ReadAllBytes(path);
    var subject = Mail.Parse(bytes).Subject;
    Console.WriteLine(
        $"{subject}: {item.Marks}");
}

Unzip the example, then dotnet run.

Prints each delivered message’s subject and flags.

Text
Maps: Seen, Flagged
Tickets: Recent

The full program

The example’s three fictional messages are stored in this layout:

Text
inbox/
  cur/001;2,FS   Subject: Maps
  new/002        Subject: Tickets
  tmp/003        Subject: Staged

Here is cur/001;2,FS. The other files have the same header layout with their own sender, date, subject, and a one-line body.

Text
From: Ada <ada@example.test>
Date: Thu, 19 Nov 2026 09:00:00 +0000
Subject: Maps
 
The map is ready.

MaildirStore lists cur before new. The program prints the three flags separately so you can see that “recent” and “seen” are different states.

C#
using RecursiveAI.OneMail;
using RecursiveAI.OneMail.Sources;
using RecursiveAI.OneMail.Stores;
using RecursiveAI.OneMail.Stores.Maildir;
 
var store = new MaildirStore(new PhysicalStoreFileSystem("inbox"));
foreach (var entry in store.Enumerate())
{
    using var file = store.Open(entry);
    using var bytes = file.OpenRead(0, file.Length);
    var message = Mail.Parse(bytes);
    Console.WriteLine($"{entry.Subdirectory}: {message.Subject}");
    Console.WriteLine($"  Seen={entry.Marks.HasFlag(MessageMarks.Seen)}, " +
        $"Flagged={entry.Marks.HasFlag(MessageMarks.Flagged)}, " +
        $"Recent={entry.Marks.HasFlag(MessageMarks.Recent)}");
}

dotnet run prints:

Text
Cur: Maps
  Seen=True, Flagged=True, Recent=False
New: Tickets
  Seen=False, Flagged=False, Recent=True

Point PhysicalStoreFileSystem at the directory above cur and new, not at cur itself; missing directories are skipped and can make the listing look empty.

Variations

Read only flagged messages. Add this inside the loop in the snippet at the top, before reading the file.

C#
// Inside the foreach loop:
if (!item.Marks.HasFlag(MessageMarks.Flagged))
    continue;
Text
Maps: Seen, Flagged

Parse an EML file · Read an MBOX file


The short answer

Open the Maildir root with MaildirStore, enumerate its entries, and read item.Marks for flags. Open and parse a message only when you need data inside it, such as the subject. The flags used here come from the filename and directory, not from the message headers.

What do Maildir flags mean?

In 001;2,FS, 001 is the unique part, ;2, starts the version-2 info field, and FS marks the message as flagged and seen. The Maildir convention uses :2,; OneMail reads both :2, and ;2, on every platform. The sample uses a semicolon because Windows doesn’t allow a colon in the filename.

LetterMeaning in OneMail
DDraft
FFlagged
PForwarded (“passed”)
RAnswered
SSeen
TDeleted (trashed)

Recent has no letter in the sample filename. OneMail adds it because the file is in new. A message in cur without S isn’t marked seen merely because it lives there. Lowercase letters are keyword slots, not additional copies of the uppercase flags. See the Maildir naming and keyword rules.

How do I open and read a Maildir folder on Windows?

Point the example at a local folder containing cur, new, and tmp. Use the semicolon form for the version-2 info names when creating or copying fixtures onto Windows. This is a local file operation; there’s no IMAP server or login involved. Enumerate() without a folder argument reads the root mailbox. If you need subfolders, the same store supports the Maildir++ naming convention, where a folder like .Archive.2024 sits under the root.

tmp contains messages that haven’t been delivered into the mailbox yet, so the staged subject in the sample doesn’t print. Dot-prefixed names inside cur and new are skipped too. Within each of those directories the names are sorted ordinally; the listing isn’t a sort by the date in the email.

When you’re filtering by flags, use HasFlag as in the variation rather than comparing the entire Marks value with Flagged. That way the sample’s Maps message matches even though it also has Seen set.

All onemail recipes