How to Get Started with Aspose.Email FOSS for Python

aspose-email-foss for Python is a free, MIT-licensed library for creating, reading, and converting Outlook MSG files and CFB containers — no Microsoft Office required, no native extensions, pure Python from PyPI.

Step-by-Step Guide

Step 1: Install the Package

Install from PyPI with pip:

pip install aspose-email-foss

Verify the install loaded correctly:

from aspose.email_foss.msg import MapiMessage
print("aspose-email-foss is ready.")

Step 2: Import Required Classes

Import the modules you need for message creation, property assignment, and format conversion:

from datetime import datetime, timezone
from aspose.email_foss import msg
from aspose.email_foss.msg import MapiMessage, PropertyId

Step 3: Create an MSG File

Use MapiMessage.create() to build a message with a subject and body. Set sender metadata with PropertyId constants, add recipients, and attach a file.

message = MapiMessage.create("Getting Started", "Hello from aspose-email-foss!")

message.set_property(PropertyId.SENDER_NAME, "Build Agent")
message.set_property(PropertyId.SENDER_EMAIL_ADDRESS, "agent@example.com")
message.set_property(
    PropertyId.MESSAGE_DELIVERY_TIME,
    datetime(2026, 1, 1, 9, 0, tzinfo=timezone.utc),
)

message.add_recipient("alice@example.com", display_name="Alice Example")
message.add_attachment("notes.txt", b"Meeting notes go here.\n", mime_type="text/plain")

message.save("getting-started.msg")
print("getting-started.msg written.")

Step 4: Read the MSG File Back

Load the saved file using MapiMessage.from_file() as a context manager. Access the subject and body properties directly from the returned object.

with MapiMessage.from_file("getting-started.msg") as message:
    print(f"Subject: {message.subject}")
    print(f"Body   : {message.body}")

Step 5: Convert the MSG to EML

to_email_bytes() converts the loaded message to RFC 5322 format. Write the result to a .eml file with the standard library.

from pathlib import Path

with MapiMessage.from_file("getting-started.msg") as message:
    Path("getting-started.eml").write_bytes(message.to_email_bytes())
    print("getting-started.eml written.")

Common Issues and Fixes

ModuleNotFoundError: No module named 'aspose' The package is not installed in the active Python environment. Run pip install aspose-email-foss in the same virtual environment you are using to run your script. Confirm with pip show aspose-email-foss.

FileNotFoundError when calling MapiMessage.from_file() The path you passed does not exist or uses the wrong separator for your OS. Use pathlib.Path to construct paths portably: MapiMessage.from_file(Path("folder") / "file.msg").

MSG file opens in Outlook but shows no subject MapiMessage.create() accepts the subject as the first positional argument. If you passed an empty string, Outlook shows the message as untitled. Pass a non-empty string or set it explicitly with set_property(PropertyId.SUBJECT, "My Subject").

EML conversion produces an empty body to_email_bytes() uses body_html if set, and falls back to body. Confirm that at least one of these properties is non-empty after loading the MSG with from_file().

Unicode content in recipients or subject is truncated Pass unicode_strings=True to MapiMessage.create() to ensure string properties are stored in Unicode (PT_UNICODE) rather than ANSI (PT_STRING8).

Frequently Asked Questions

Does aspose-email-foss require Microsoft Office?

No. The library is entirely self-contained. It reads and writes the binary MSG and CFB formats natively in Python without any dependency on Microsoft Office, COM automation, or Win32 APIs.

Can I use this library on Linux or macOS?

Yes. aspose-email-foss is pure Python and runs on any platform that supports Python 3.10 or later — including Windows, macOS, Linux, Docker containers, and serverless functions.

Is the library free for commercial use?

Yes. It is released under the MIT License. You may use, modify, and redistribute it for any purpose, including commercial applications, without royalties or attribution requirements beyond the license text.

How do I add CC and BCC recipients?

Pass recipient_type=msg.RECIPIENT_TYPE_CC or msg.RECIPIENT_TYPE_BCC as the third argument to add_recipient():

message.add_recipient("bob@example.com", display_name="Bob", recipient_type=msg.RECIPIENT_TYPE_CC)

How do I embed one MSG inside another?

Use MapiMessage.add_embedded_message_attachment(), passing the inner MapiMessage object as the first argument:

inner = MapiMessage.create("Inner message", "Embedded body.")
outer = MapiMessage.create("Outer message", "See attachment.")
outer.add_embedded_message_attachment(inner, "inner.msg")
outer.save("outer.msg")