Read Apple Mail EMLX files
Apple Mail keeps each message in an EMLX file: its length in bytes on a line of its own, the message, and an XML property list of metadata. EmlxReader reads one into an EmlxEntry.
Apple doesn’t document the format, so the package follows the layout that open-source readers agree on. Anything it doesn’t know in the property list is kept, not rejected.
Read a file
using DataStandardizer.File.InternetMessage;
using var reader = new EmlxReader("123.emlx");
var entry = reader.ReadEntry();
Console.WriteLine(entry.Message.Subject);
Console.WriteLine(entry.Metadata.DateReceived);
Console.WriteLine(entry.Metadata.MessageFlags);
Saved by Mail
1/Nov/2026 09:00:05 +00:00
Read, Answered
entry.Message is an ImfMessage, with all that gives. A file holds one entry, so it can be read only once.
Read the metadata
EmlxMetadata has properties for the keys that are well known:
| Property | Key | Meaning |
|---|---|---|
DateReceived, DateLastViewed | date-received, date-last-viewed | Dates, in UTC. |
Subject | subject | The subject, which Mail keeps apart from the message. |
RemoteId | remote-id | The identifier of the message on its server. |
Flags | flags | The whole integer. |
MessageFlags | flags | The single-bit flags, as EmlxMessageFlags. |
AttachmentCount, PriorityLevel | flags | Values that the flags key holds. |
These come from community documentation, and may not be right for every version of Mail. A key whose value isn’t of the kind expected gives null from its property, and the value itself is still in Entries.
Every key and value is in Entries, in order, whether the package knows it or not:
foreach (var pair in entry.Metadata.Entries)
{
Console.WriteLine($"{pair.Key} {pair.Value.Kind} {pair.Value.Text}");
}
if (entry.Metadata.TryGetValue("x-my-key", out var value))
{
Console.WriteLine(value.Text);
}
date-received Integer 1793523605
flags Integer 5
remote-id String 4711
subject String Saved by Mail
x-my-key String kept
kept
Read a partial file
Mail may keep a large part of a message in an .emlxpart file of its own, and leave an entity with an X-Apple-Content-Length field and an empty body. So 123.partial.emlx keeps part 2 in 123.2.emlxpart.
With nothing else given, the message is read without that content. No option is needed. The reader records a MissingEmlxPart diagnostic, and lists the part in MissingParts:
using var reader = new EmlxReader("456.partial.emlx");
var entry = reader.ReadEntry();
foreach (var part in entry.MissingParts)
{
Console.WriteLine($"{part.Path} {part.GetPartFileName("456.partial.emlx")} {part.Entity.FileName}");
}
2 456.2.emlxpart big.pdf
To have the content, give ReadEntry an EmlxPartResolver. It returns a stream of the bytes of the part, still in its transfer encoding, which the reader reads to its end and disposes, or null if the content isn’t available:
using var reader = new EmlxReader("456.partial.emlx");
var entry = reader.ReadEntry(part =>
{
var path = part.GetPartFileName("456.partial.emlx");
return File.Exists(path) ? File.OpenRead(path) : null;
});
var pdf = entry.Message.Attachments[0].GetContent();
GetPartFileName only works out the name. Opening the file is left to the resolver, so a reader of a file from elsewhere can check the path, and a message that isn’t on disk can be supplied from wherever it is.
ContentLength gives the value of the X-Apple-Content-Length field. Community documentation doesn’t say whether it counts the bytes before or after the transfer encoding, so it is for information only.
Save a message as an .eml file
A message in an EMLX file has LF line breaks. Writing it with an ImfWriter gives it the CRLF that RFC 5322 §2.1 requires:
using var writer = new ImfWriter("123.eml");
writer.WriteMessage(entry.Message);
A message with CRLF line breaks in an EMLX file isn’t one the reader accepts, as it reads a line feed as the line break.
Write a file
EmlxWriter works out the byte count, and writes the message with LF line breaks:
var metadata = new EmlxMetadata
{
DateReceived = DateTimeOffset.UtcNow,
Flags = (long)(EmlxMessageFlags.Read | EmlxMessageFlags.Answered),
RemoteId = "4711"
};
metadata.Set("x-my-key", EmlxPlistValue.FromString("kept"));
using var writer = new EmlxWriter("123.emlx");
writer.WriteEntry(new EmlxEntry(message, metadata));
An entry that was read and hasn’t changed is written back byte for byte. A change to the metadata writes the whole property list again, as Apple’s tools lay it out, with the keys that weren’t changed still in order. A file holds one entry, so a second write throws InvalidOperationException.
Read damaged files
| Problem | Option | With it |
|---|---|---|
| The first line isn’t a byte count, or the count doesn’t fit the file | AllowInvalidEmlxByteCount | The reader discards the line, and takes the last <?xml, or failing that the last <plist, as the start of the property list. This is a best guess: in a file with no property list, a message that holds such text is cut short there. |
| The property list is missing or not well formed | AllowInvalidEmlxMetadata | The metadata has no entries, IsWellFormed is false, and RawBytes keeps the bytes. |
Each records a diagnostic in entry.Diagnostics.
The reader holds the whole file while it reads it, so the limits in ImfOptions apply. See Limits for hostile input.