Введение
Aspose.Email FOSS для Python (aspose-email-foss) — это лицензированная по MIT Python библиотека для работы с файлами Outlook MSG, RFC-5322 сообщениями EML и структурами хранения Compound File Binary (CFB). Библиотека не требует нативных расширений и устанавливается напрямую из PyPI.
Библиотека решает распространённый пробел в разработке Python: чтение и запись файлов Outlook .msg без необходимости установленного Outlook или проприетарного SDK. Она также раскрывает полный формат контейнера CFB, лежащий в основе файлов .msg, что делает её подходящей для задач, от миграции сообщений до инспекции хранилища.
Библиотека поставляется с типизированным интерфейсом API, охватывающим построение MAPI-сообщений, управление получателями и вложениями, сериализацию свойств и обратные преобразования CFB-документов.
Ключевые возможности
Создание и сериализация файлов MSG
MapiMessage.create() создает новое MAPI-сообщение из строки темы и тела. Затем можно добавить типизированные свойства, получателей и бинарные вложения, после чего сериализовать результат в байты с помощью to_bytes().
import datetime
from aspose.email_foss.msg.mapi_message import MapiMessage, PropertyId
message = MapiMessage.create("Quarterly Report", "Please review the attached report.")
message.set_property(PropertyId.SENDER_NAME, "Alice")
message.set_property(PropertyId.SENDER_EMAIL_ADDRESS, "alice@example.com")
message.set_property(
PropertyId.MESSAGE_DELIVERY_TIME,
datetime.datetime(2026, 3, 15, 10, 30, tzinfo=datetime.timezone.utc),
)
message.add_recipient("bob@example.com", display_name="Bob")
message.add_attachment("report.pdf", b"%PDF-1.4 ...", mime_type="application/pdf")
raw_bytes = message.to_bytes()
Чтение существующих файлов MSG
MapiMessage.from_file() читает существующий файл .msg с диска. Вы также можете восстановить сообщение из необработанных байтов, передав CFBReader через MsgReader и MsgDocument.
from aspose.email_foss.msg.mapi_message import MapiMessage
from aspose.email_foss.msg.reader import MsgReader, MsgDocument
from aspose.email_foss.cfb.reader import CFBReader
# Read from file path
msg = MapiMessage.from_file("message.msg")
print(msg.subject)
# Or reconstruct from bytes
msg2 = MapiMessage.from_msg_document(
MsgDocument.from_reader(MsgReader(CFBReader(raw_bytes)))
)
print(msg2.subject)
for att in msg2.attachments:
print(att.filename, len(att.data), "bytes")
Преобразование между MAPI и RFC-5322 EML
MapiMessage.from_email_message() преобразует стандартный объект Python email.message.EmailMessage в сообщение MAPI, сохраняя тему, получателей, тело и вложения. Обратное преобразование использует to_email_message().
from email.message import EmailMessage
from aspose.email_foss.msg.mapi_message import MapiMessage
# Build a standard Python email
eml = EmailMessage()
eml["Subject"] = "Meeting notes"
eml["From"] = "alice@example.com"
eml["To"] = "bob@example.com"
eml.set_content("Notes from today's meeting.")
# Convert to MAPI and serialize as .msg
mapi = MapiMessage.from_email_message(eml)
with open("meeting-notes.msg", "wb") as f:
f.write(mapi.to_bytes())
# Round-trip back to EML
recovered = mapi.to_email_message()
print(recovered["Subject"])
Хранилище Compound File Binary (CFB)
Библиотека включает отдельный слой CFB (CFBReader, CFBWriter, CFBDocument, CFBStorage, CFBStream) для чтения и записи формата Compound File Binary независимо от MAPI. Это полезно для изучения сырой структуры хранилища файлов .msg или для создания пользовательских контейнеров составных файлов.
from aspose.email_foss.cfb.writer import CFBWriter, CFBDocument, CFBStorage, CFBStream
from aspose.email_foss.cfb.reader import CFBReader
# Build a CFB document with nested storage
root = CFBStorage("Root Entry")
root.add_stream(CFBStream("Metadata", b"meta-payload"))
nested = root.add_storage(CFBStorage("Attachments"))
nested.add_stream(CFBStream("Attachment1", b"binary-content"))
doc = CFBDocument(root=root, major_version=3)
data = CFBWriter.to_bytes(doc)
# Read it back
reader = CFBReader(data)
entry = reader.resolve_path(["Attachments", "Attachment1"])
print(reader.get_stream_data(entry.stream_id))
Доступ к свойствам MAPI
iter_properties() возвращает все свойства MAPI сообщения в виде объектов MapiProperty. Именованные свойства (PidLidTag и PidNameTag) доступны через MapiNamedProperty. MapiPropertyCollection предоставляет доступ к свойствам в виде словаря.
from aspose.email_foss.msg.mapi_message import MapiMessage
msg = MapiMessage.from_file("message.msg")
for prop in msg.iter_properties():
print(hex(prop.property_id), prop.property_type, repr(prop.value)[:60])
Быстрый старт
pip install aspose-email-fossimport datetime
from aspose.email_foss.msg.mapi_message import MapiMessage, PropertyId
from aspose.email_foss.msg.reader import MsgReader, MsgDocument
from aspose.email_foss.cfb.reader import CFBReader
# Create a message
message = MapiMessage.create("Hello", "This is the body.")
message.set_property(PropertyId.SENDER_NAME, "Sender")
message.set_property(PropertyId.SENDER_EMAIL_ADDRESS, "sender@example.com")
message.add_recipient("recipient@example.com", display_name="Recipient")
message.add_attachment("note.txt", b"attachment content", mime_type="text/plain")
# Serialize and reload
raw = message.to_bytes()
reloaded = MapiMessage.from_msg_document(
MsgDocument.from_reader(MsgReader(CFBReader(raw)))
)
email = reloaded.to_email_message()
print("Subject:", email["Subject"])
print("From:", email["From"])
Поддерживаемые форматы
| Формат | Расширение | Читать | Записать |
|---|---|---|---|
| Сообщение | .msg | ✓ | ✓ |
| CFB | .cfb | ✓ | ✓ |
| eml | .eml | ✓ | ✓ |
Файлы MSG читаются через MapiMessage.from_file() и MsgReader. Доступ к EML осуществляется через мост конвертации from_email_message() / to_email_message(). CFB-контейнеры обрабатываются напрямую CFBReader и CFBWriter.
Открытый исходный код и лицензирование
Aspose.Email FOSS для Python выпущен под лицензией MIT. Исходный код доступен на GitHub, а пакет распространяется через PyPI под именем aspose-email-foss. Лицензия MIT позволяет использовать в коммерческих приложениях без роялти и требований к указанию авторства, кроме включения лицензии.