مقدمة

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 قيمة التعداد. استخدم 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() تسلسل مباشرة إلى bytes أو نص.

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() يقوم بتسلسل المستند مرة أخرى إلى disk بشكل حتمي.

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 خاصية تُعيد tuple من سلاسل التحذير دون رفع استثناء، مما يتيح لك تحديد مدى الصرامة في التعامل مع الملفات غير المتوافقة.

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. يمكنك استخدامه في المشاريع الشخصية والداخلية والتجارية دون أي قيود. الشيفرة المصدرية متاحة على GitHub.

البدء