Введение

Aspose.Email FOSS for Python goes beyond basic message creation. The library exposes the full depth of the MAPI property model, letting you read, write, and query individual properties by ID and type. It handles recipients, attachments, and embedded messages as first-class objects, and provides bidirectional conversion between the MSG binary format and Python’s standard email.message.EmailMessage.

На уровне контейнера читатель и писатель CFB предоставляют вам детерминированный контроль над документами Compound File Binary. Вы можете обходить иерархии хранилищ, извлекать необработанные данные потоков, создавать новые контейнеры с нуля и сериализовать их обратно в байты. Оба CFBError и MsgError предоставляют структурированную обработку исключений для некорректного ввода.

В этом посте подробно рассматриваются все возможности с проверенными примерами кода, взятыми непосредственно из тестового набора библиотеки и примерных скриптов.

Что включено

Доступ к свойствам MAPI

Каждый файл MSG построен на свойствах MAPI. MapiMessage предоставляет set_property() и get_property() для работы со свойствами по их PropertyId значению enum. Используйте iter_properties() для перечисления всех свойств сообщения, или get_property_value() для непосредственного получения значения с необязательной декодировкой типа.

from aspose.email_foss import msg

message = msg.MapiMessage.create("Status report", "Weekly update attached.")

message.set_property(msg.PropertyId.SENDER_NAME, "Build Agent")
message.set_property(msg.PropertyId.SENDER_EMAIL_ADDRESS, "build.agent@example.com")
message.set_property(msg.PropertyId.DISPLAY_TO, "Alice Example; Bob Example")
message.set_property(msg.PropertyId.DISPLAY_CC, "Carol Example")
message.set_property(msg.PropertyId.DISPLAY_BCC, "Ops Archive")
message.set_property(
    msg.PropertyId.TRANSPORT_MESSAGE_HEADERS,
    "X-Environment: production\nX-Workflow: weekly-report\n",
)
message.save("report.msg")

Чтобы прочитать свойства из существующего файла:

from aspose.email_foss import msg

with msg.MapiMessage.from_file("report.msg") as loaded:
    print(f"Subject: {loaded.subject}")
    print(f"Body: {loaded.body}")

    for prop in loaded.iter_properties():
        print(f"tag=0x{prop.property_tag:08X}")

Получатели и вложения

Добавьте получателей с add_recipient(), указывая отображаемое имя и тип получателя (To, CC или BCC). Прикрепляйте файлы с add_attachment() используя необработанные байты и MIME‑тип. Для вложенных сообщений, add_embedded_message_attachment() встраивает полное MapiMessage в качестве дочернего объекта внутри родителя.

from aspose.email_foss import msg

message = msg.MapiMessage.create("Team update", "See attached notes.")

message.add_recipient("alice@example.com", display_name="Alice Example")
message.add_recipient(
    "carol@example.com",
    display_name="Carol Example",
    recipient_type=msg.RECIPIENT_TYPE_CC,
)
message.add_recipient(
    "archive@example.com",
    display_name="Ops Archive",
    recipient_type=msg.RECIPIENT_TYPE_BCC,
)

message.add_attachment("notes.txt", b"Meeting notes content\n", mime_type="text/plain")
message.add_attachment("data.bin", b"\x00\x01\x02\x03", mime_type="application/octet-stream")
message.save("team-update.msg")

Чтобы просмотреть вложения в существующем сообщении:

from aspose.email_foss import msg

with msg.MapiMessage.from_file("team-update.msg") as loaded:
    for att in loaded.iter_attachments_info():
        print(f"name={att.filename} mime={att.mime_type} size={len(att.data)}")
        print(f"  embedded={att.is_embedded_message} storage={att.storage_name}")

Преобразование MSG в EmailMessage

Библиотека преобразует в обоих направлениях между MSG и Python’s email.message.EmailMessage. Используйте to_email_message() для создания MIME‑объекта, соответствующего стандартам, или from_email_message() для импорта существующего EmailMessage в формат MSG. Удобные методы to_email_bytes() и to_email_string() сериализуют напрямую в байты или текст.

from aspose.email_foss import msg

with msg.MapiMessage.from_file("example.msg") as loaded:
    email_msg = loaded.to_email_message()

    print(f"content_type: {email_msg.get_content_type()}")
    print(f"is_multipart: {email_msg.is_multipart()}")
    print(f"headers: {len(email_msg)}")

    for key, value in email_msg.items():
        print(f"  {key}: {value}")

    body_part = email_msg.get_body(preferencelist=("plain", "html"))
    if body_part is not None:
        print(f"body: {body_part.get_content()[:200]}")

Круговой проход CFB‑контейнера

Создавайте и сериализуйте контейнеры Compound File Binary независимо от уровня MSG. CFBDocument.from_file() загружает существующий контейнер в изменяемую модель документа с CFBStorage и CFBStream узлы. CFBWriter.write_file() детерминированно сериализует документ обратно на диск.

from aspose.email_foss.cfb import CFBDocument, CFBReader, CFBWriter

reader = CFBReader.from_file("container.cfb")
document = CFBDocument.from_reader(reader)
reader.close()

output = CFBWriter.to_bytes(document)
print(f"Serialized {len(output)} bytes")

Обработка ошибок

Библиотека вызывает CFBError для некорректного содержимого CFB и MsgError для неверной структуры MSG. MapiMessage также предоставляет validation_issues свойство, которое возвращает кортеж строк предупреждений без генерации исключения, позволяя вам решить, насколько строго обрабатывать файлы, не соответствующие требованиям.

from aspose.email_foss.cfb import CFBReader, CFBError
from aspose.email_foss.msg import MsgReader, MsgError

try:
    reader = CFBReader.from_file("corrupted.cfb")
except CFBError as e:
    print(f"CFB parse error: {e}")

try:
    reader = MsgReader.from_file("malformed.msg")
except MsgError as e:
    print(f"MSG parse error: {e}")

Быстрый старт

pip install aspose-email-foss>=26.3

Загрузите существующий MSG, прочитайте его метаданные и выведите список вложений:

from aspose.email_foss import msg

with msg.MapiMessage.from_file("inbox-message.msg") as message:
    print(f"Subject: {message.subject}")
    print(f"Body preview: {message.body[:200] if message.body else '(empty)'}")

    for att in message.iter_attachments_info():
        print(f"Attachment: {att.filename} ({att.mime_type}, {len(att.data)} bytes)")

    issues = message.validation_issues
    if issues:
        print(f"Warnings: {issues}")

Поддерживаемые форматы

ФорматИмпортЭкспорт
MSGДаДа
CFBДаДа

Открытый исходный код и лицензирование

Aspose.Email FOSS for Python is released under the MIT License. Вы можете использовать его в личных, внутренних и коммерческих проектах без ограничений. Исходный код доступен на GitHub.

Начало работы