مقدمه

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 تبدیل می‌کند 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.


شروع