Вступ

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.

Початок роботи