Features and Functionalities

This page covers every major feature of aspose-email-foss 26.3 with working Python examples.

Reading MSG Files

Load an MSG file and access its core properties:

from aspose.email_foss.msg import MapiMessage

msg = MapiMessage.from_file("message.msg")

print(f"Subject: {msg.subject}")
print(f"Body: {msg.body}")
print(f"HTML Body: {msg.body_html}")
print(f"Message Class: {msg.message_class}")

Creating MSG Files

Create a new message from scratch:

from aspose.email_foss.msg import MapiMessage

msg = MapiMessage.create("Meeting Notes", "Please find the notes attached.")
msg.save("new_message.msg")

Set subject and body on an existing message:

msg.subject = "Updated Subject"
msg.body = "Updated body text"
msg.save("updated.msg")

Recipients

Add recipients with display names and types:

from aspose.email_foss.msg import MapiMessage

msg = MapiMessage.create("Hello", "Message body")
msg.add_recipient("alice@example.com", display_name="Alice Smith")
msg.add_recipient("bob@example.com", display_name="Bob Jones", recipient_type="cc")
msg.save("with_recipients.msg")

Attachments

Add binary file attachments:

with open("report.pdf", "rb") as f:
    data = f.read()

msg.add_attachment("report.pdf", data, mime_type="application/pdf")
msg.save("with_attachment.msg")

Embed an MSG message as a nested attachment:

inner = MapiMessage.create("Inner Subject", "Inner body")
msg.add_embedded_message_attachment(inner, "embedded.msg", "application/vnd.ms-outlook")
msg.save("with_embedded.msg")

MAPI Properties

Read and write MAPI properties by property ID:

from aspose.email_foss.msg import CommonMessagePropertyId

# Read a property
subject = msg.get_property(CommonMessagePropertyId.SUBJECT)

# Set a property
msg.set_property(CommonMessagePropertyId.SUBJECT, "New Subject")

Iterate all properties:

for prop in msg.iter_properties():
    print(f"Tag: {prop.property_tag:#010x}")

Email Conversion

Convert between MSG (MAPI) and email (RFC 5322) formats:

# MSG to email string
email_str = msg.to_email_string()
print(email_str[:500])

# MSG to EmailMessage object
email_msg = msg.to_email_message()

# EmailMessage back to MapiMessage
msg2 = MapiMessage.from_email_message(email_msg)
msg2.save("roundtrip.msg")

Low-Level CFB Operations

Read CFB container structure directly:

from aspose.email_foss.cfb import CFBReader

reader = CFBReader.from_file("message.msg")
print(f"File size: {reader.file_size()} bytes")
print(f"Sectors: {reader.fat_sector_count()}")
print(f"Entries: {reader.directory_entry_count()}")

for entry in reader.iter_storages():
    print(f"Storage: {entry}")

for entry in reader.iter_streams():
    print(f"Stream: {entry}")

reader.close()

Write CFB documents:

from aspose.email_foss.msg import MsgWriter

data = msg.to_bytes()
with open("output.msg", "wb") as f:
    f.write(data)

Tips and Best Practices

Always call msg.close() or use a context manager when done reading to release file handles
Use msg.validation_issues to check for MSG format compliance issues
The strict parameter in MapiMessage.from_file() controls error tolerance — set to False for lenient parsing
Binary attachment data is not loaded into memory until accessed; iterate iter_attachments_info() for metadata only
Use to_email_string() for quick text previews without full email object construction

Common Issues

Issue	Cause	Fix
`CFBError` when loading	Not a valid CFB/MSG file	Verify the file is an actual Outlook MSG
Empty body after load	Body stored in HTML only	Check `msg.body_html` instead of `msg.body`
Missing recipients	MSG has no recipient storages	Recipients are optional in MSG format; check `iter_attachments_info()`

FAQ

What MSG format versions are supported?

The library reads and writes MSG files in CFB v3 and v4 format, compatible with Microsoft Outlook.

Can I read EML files?

Not directly. The library handles MSG format. Use MapiMessage.from_email_message() to convert from RFC 5322 EmailMessage objects.

Is thread-safety supported?

Each MapiMessage and CFBReader instance is independent. Concurrent access to separate instances from separate threads is safe.

API Reference Summary

Class / Method	Description
`MapiMessage`	High-level MSG message representation
`MapiMessage.from_file()`	Load an MSG file
`MapiMessage.create()`	Create a new MSG message
`MapiMessage.save()`	Save to MSG file
`MapiMessage.to_email_message()`	Convert to EmailMessage (RFC 5322)
`MapiMessage.from_email_message()`	Convert from EmailMessage to MSG
`MapiMessage.add_recipient()`	Add a recipient
`MapiMessage.add_attachment()`	Add a binary attachment
`MapiAttachment`	Attachment on a message
`MapiRecipient`	Recipient on a message
`MapiProperty`	MAPI property entry
`CFBReader`	Low-level CFB container reader
`CFBWriter`	Low-level CFB container writer
`MsgReader`	Low-level MSG structure reader