مقدمه

Aspose.Email FOSS برای Python (aspose-email-foss) یک کتابخانه Python تحت مجوز MIT است که برای کار با فایل‌های 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"])

ذخیره‌سازی باینری فایل ترکیبی (CFB)

این کتابخانه شامل لایهٔ مستقل CFB (CFBReader, CFBWriter, CFBDocument, CFBStorage, CFBStream) برای خواندن و نوشتن فرمت باینری فایل ترکیبی به‌صورت مستقل از 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-foss
import 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 اجازه استفاده در برنامه‌های تجاری را بدون حق‌الزحمه یا نیاز به ارجاع جزئی جز افزودن مجوز می‌دهد.


شروع کار

منابع مرتبط