Table of Contents

OutlookMessage Class

Definition

Namespace
Bodu.Formats.Outlook
Assembly
Bodu.Formats.Outlook.Msg.dll
Package
Bodu.Formats.Outlook.Msg 1.3.0
Source
OutlookMessage.Attachments.cs

Provides a disposable, read-only session over an Outlook message (.msg / MS-OXMSG), exposing every decoded MAPI property together with curated conveniences for the common message fields.

public sealed class OutlookMessage : IDisposable
Inheritance
OutlookMessage
Implements
Inherited Members
Extension Methods

Remarks

A .msg file is an OLE2 compound file; opening a message opens the container through CompoundFile and decodes the root property stream eagerly, so the property surface is available without further I/O. The session owns the container and, unless the caller opts to leave it open, the source stream; dispose the message when reading is complete.

Every property is reachable through Properties; the scalar conveniences (Subject, SenderName, the time stamps, and the rest) are lazy views over that collection and return null when the underlying property is absent.

The session is single-threaded: its members, and the members of every recipient, attachment, and nested message obtained from it, must not be called concurrently. The recipients, the attachments, and the named-property map are decoded on first access and cached without synchronization.

using Bodu.Formats.Outlook;

using var message = OutlookMessage.OpenRead("invoice.msg");

Console.WriteLine(message.Subject);
Console.WriteLine(message.SenderEmailAddress);

Properties

Attachments

Gets the attachments of the message, in storage-index order.

public IReadOnlyList<OutlookAttachment> Attachments { get; }

Property Value

IReadOnlyList<OutlookAttachment>

The attachment list; empty when the message declares no attachments.

Remarks

Under the tolerant validation levels an attachment storage with no __properties_version1.0 stream is omitted from the list.

Exceptions

ObjectDisposedException

The message has been disposed.

OutlookMsgFormatException

Thrown under strict validation when the attachment storages are inconsistent with the declared count, or an attachment storage has no property stream.

BodyHtml

Gets the HTML body.

public string? BodyHtml { get; }

Property Value

string

The PidTagHtml payload decoded through the message's internet code page (falling back to the message code page), or the string value when the writer stored it as a string, ending at its first NUL; null when absent. The body is decoded once and the same instance returned thereafter.

Exceptions

ObjectDisposedException

The message has been disposed.

BodyRtf

Gets the RTF body, decompressed from PidTagRtfCompressed per MS-OXRTFCP.

public string? BodyRtf { get; }

Property Value

string

The RTF text, or null when the property is absent or DecompressRtf is disabled (the raw payload stays available through Properties). The body is decompressed once and the same instance returned thereafter.

Exceptions

ObjectDisposedException

The message has been disposed.

OutlookMsgFormatException

The compressed payload is malformed, fails its checksum, or decompresses beyond MaxDecompressedRtfBytes.

BodyText

Gets the plain-text body.

public string? BodyText { get; }

Property Value

string

The PidTagBody value, or null when absent.

EmbeddedDepth

Gets the embedded-message nesting depth of this session: zero for a message opened from a file or stream, one more for each level opened through OpenMessage().

public int EmbeddedDepth { get; }

Property Value

int

The nesting depth.

InternetMessageId

Gets the internet message identifier.

public string? InternetMessageId { get; }

Property Value

string

The PidTagInternetMessageId value, or null when absent.

MessageClass

Gets the message class (for example, IPM.Note).

public string? MessageClass { get; }

Property Value

string

The PidTagMessageClass value, or null when absent.

Properties

Gets every decoded MAPI property of the message.

public MapiPropertyCollection Properties { get; }

Property Value

MapiPropertyCollection

The tag-addressed property collection.

Exceptions

ObjectDisposedException

The message has been disposed.

ReceivedTime

Gets the time the message was delivered.

public DateTimeOffset? ReceivedTime { get; }

Property Value

DateTimeOffset?

The PidTagMessageDeliveryTime value, or null when absent.

Recipients

Gets the recipients of the message, in storage-index order.

public IReadOnlyList<OutlookRecipient> Recipients { get; }

Property Value

IReadOnlyList<OutlookRecipient>

The recipient list; empty when the message declares no recipients.

Remarks

Under the tolerant validation levels a recipient storage with no __properties_version1.0 stream is omitted from the list.

Exceptions

ObjectDisposedException

The message has been disposed.

OutlookMsgFormatException

Thrown under strict validation when the recipient storages are inconsistent with the declared count, or a recipient storage has no property stream.

SenderEmailAddress

Gets the sender email address.

public string? SenderEmailAddress { get; }

Property Value

string

The PidTagSenderEmailAddress value, or null when absent.

SenderName

Gets the sender display name.

public string? SenderName { get; }

Property Value

string

The PidTagSenderName value, or null when absent.

SentTime

Gets the time the message was submitted by the sending client.

public DateTimeOffset? SentTime { get; }

Property Value

DateTimeOffset?

The PidTagClientSubmitTime value, or null when absent.

Subject

Gets the message subject, with the MAPI subject-prefix marker removed when a writer stored one.

public string? Subject { get; }

Property Value

string

The normalized PidTagSubject value, or null when absent; the stored value remains available through Properties.

TransportMessageHeaders

Gets the transport message headers.

public string? TransportMessageHeaders { get; }

Property Value

string

The PidTagTransportMessageHeaders value, or null when absent.

Methods

Dispose()

Releases the container and, unless it was left open, the source stream. Disposing a nested message obtained from an attachment is a no-op - the root session owns the container, and the nested session's decoded properties stay readable until the root is disposed, after which every nested session throws ObjectDisposedException as well.

public void Dispose()

IsMsgFile(Stream)

Determines whether a stream carries an Outlook message: an OLE2 compound file whose root storage holds the message property stream.

public static bool IsMsgFile(Stream stream)

Parameters

stream Stream

The readable, seekable stream to sniff; its position is restored before returning.

Returns

bool

true when the stream looks like a .msg file.

Remarks

The check does not require the conventional root class identifier - real-world writers frequently omit it - so the presence of the __properties_version1.0 stream is the discriminator.

Exceptions

ArgumentNullException

Thrown if stream is null.

Open(Stream, OutlookMessageReaderOptions, bool)

Opens a message from a stream with explicit options.

public static OutlookMessage Open(Stream stream, OutlookMessageReaderOptions options, bool leaveOpen = false)

Parameters

stream Stream

The readable, seekable source stream positioned at the container start.

options OutlookMessageReaderOptions

The reader options.

leaveOpen bool

true to leave the stream open when the message is disposed.

Returns

OutlookMessage

The opened message session.

Exceptions

ArgumentNullException

Thrown if stream or options is null.

ArgumentException

Thrown if the ReadStrategy of options resolves to reading on demand and stream is not seekable.

OutlookMsgFormatException

The stream is not a compound file, the container is malformed, or the message is not valid.

OpenRead(Stream, bool)

Opens a message from a stream with default options.

public static OutlookMessage OpenRead(Stream stream, bool leaveOpen = false)

Parameters

stream Stream

The readable, seekable source stream positioned at the container start.

leaveOpen bool

true to leave the stream open when the message is disposed.

Returns

OutlookMessage

The opened message session.

Exceptions

ArgumentNullException

Thrown if stream is null.

OutlookMsgFormatException

The stream is not a compound file, the container is malformed, or the message is not valid.

OpenRead(string)

Opens a message from a file path.

public static OutlookMessage OpenRead(string path)

Parameters

path string

The path of the .msg file.

Returns

OutlookMessage

The opened message session.

Exceptions

ArgumentNullException

Thrown if path is null.

ArgumentException

path is empty or is not a valid path.

FileNotFoundException

No file exists at path.

DirectoryNotFoundException

A directory in path does not exist.

UnauthorizedAccessException

The caller does not have permission to read the file.

IOException

The file cannot be opened, for example because another process has it locked.

OutlookMsgFormatException

The file is not a compound file, the container is malformed, or the message is not valid.

TryGetNamedPropertyId(MapiNamedProperty, out ushort)

Attempts to resolve the property identifier a named property maps to in this message.

public bool TryGetNamedPropertyId(MapiNamedProperty name, out ushort id)

Parameters

name MapiNamedProperty

The named-property identity.

id ushort

When this method returns true, the file-specific identifier (at or above 0x8000) the name maps to; combine it with the expected MapiPropertyType to address Properties.

Returns

bool

true when the message maps the name.

Exceptions

ObjectDisposedException

The message has been disposed.

OutlookMsgFormatException

Under Strict, the named-property mapping storage lacks one of its GUID, entry and string streams, or its entry stream is malformed.

TryGetPropertyName(MapiPropertyTag, out MapiNamedProperty)

Attempts to resolve the named-property identity behind a property tag.

public bool TryGetPropertyName(MapiPropertyTag tag, out MapiNamedProperty name)

Parameters

tag MapiPropertyTag

A tag whose identifier is in the named range (at or above 0x8000).

name MapiNamedProperty

When this method returns true, the identity.

Returns

bool

true when the message maps the tag's identifier.

Exceptions

ObjectDisposedException

The message has been disposed.

OutlookMsgFormatException

Under Strict, the named-property mapping storage lacks one of its GUID, entry and string streams, or its entry stream is malformed.

Applies to

ProductVersions
.NET8, 10