الملفات
`files.list` و`list_all` و`iterate` و`get` و`download` و`list_links` و`list_all_links` و`iterate_links` و`create_link` و`revoke_link` و`stats` و`upload` و`delete` و`delete_many`.
كل الدوالّ
from pathlib import Path from openemail import openemail page = openemail.files.list(kind='pdf', sort='largest')file = page['items'][0] Path(file['filename']).write_bytes(openemail.files.download(file['id'])) links = openemail.files.list_all_links(file['id'])print([(link['url'], link['downloads']) for link in links]) stats = openemail.files.stats()print(stats['totals']['files'], stats['uploaded']['bytes'])كل ملف يحتفظ به صندوق البريد، من المرفقات المُرسلة والمُستلمة والملفات المرفوعة إليه، أي صفحة الملفات في التطبيق. يعيد download الملف كاملًا بصيغة bytes، والروابط هي روابط التنزيل التي خرج بها الملف، مع عدد مرات جلب كل منها، وstats هو تبويب التحليلات.
يأخذ list وlist_all وiterate المعاملات q وkind وsort، وكذلك direction (inbound أو outbound أو uploaded)، وaddress، أي ملفات عنوان واحد مقارَنًا دون تمييز بين الأحرف الكبيرة والصغيرة، وsince وuntil، بصيغة datetime أو سلسلة ISO 8601. يشمل since لحظته ويتوقف until قبلها.
تحتاج القراءة إلى files:read، ويحتاج الرفع والحذف ونشر الروابط أو سحبها إلى files:write، الذي يشمل files:read. والمفتاح الذي أُنشئ قبل أن تصير للملفات نطاقات خاصة بها مُنح النطاقات المقابلة. والمفتاح المقصور على عناوين أو نطاقات بعينها لا يرى إلا ملفاتها.
الروابط العامة
from openemail import openemail uploads = openemail.files.list_all(direction='uploaded', since='2026-09-01') file = uploads[0] link = openemail.files.create_link(file['id'], domain='acme.com')print(link['url']) openemail.files.revoke_link(file['id'], link['id'])ينشر create_link ملفًا على رابط تنزيل عام يُفتح دون تسجيل دخول ويعيده. يقع الرابط على مضيف الملفات لـ domain حين يكون لذلك النطاق مضيف، مثل files.acme.com، وإلا فعلى مضيف الملفات للعنوان الذي ينتمي إليه الملف، وإلا فعلى عنوان API. والملف الذي وصل أو خرج مع رسالة يُنسخ أولًا إلى تخزين عام، ويُرفض البرنامج أو السكربت بـ 422 file_unshareable.
كل create_link يصنع رابطًا جديدًا، لذا لا يُعاد أبدًا بعد ضياع الجواب: ابحث عن الرابط أولًا بـ list_links. ويوقف revoke_link الرابط نهائيًا، بما في ذلك في البريد الذي خرج من قبل، ويعيده مع تعيين revokedAt. وسحب الرابط مرتين آمن، والرابط غير المعروف يعطي 404.
الرفع والحذف
from pathlib import Path from openemail import openemail upload = openemail.files.upload( Path('price-list.pdf').read_bytes(), filename='price-list.pdf', content_type='application/pdf',) if upload['deletable']: openemail.files.delete(upload['id']) result = openemail.files.delete_many([ 'file_0c4e7a91d2b84f63a5e19b7d', 'file_6bb640f5b99e47deb758f1f5',])for kept in result['kept']: print(kept['filename'], kept['reason'])يخزّن upload البايتات كما هي، حتى 100 ميغابايت، باسم filename، ويعيد الملف الذي يرفق الإرسال معرّفه بصيغة {'fileId': upload['id']}. مرّر content_type، وإلا خُزّنت البايتات بوصفها application/octet-stream. ولا يُعاد أبدًا، لأن المحاولة الثانية ستخزّن نسخة ثانية.
لا يُحذف إلا ملف مرفوع لا يعتمد عليه شيء، ويذكر deletable وusage في كل ملف ذلك مسبقًا. يرفض delete أي ملف آخر بـ 409 file_in_use. ويأخذ delete_many حتى 100 معرّف، ويحذف ما يستطيع، ويبلّغ عن الباقي في kept، كلٌّ مع سببه، وفي missing.
يقبل upload قيمة bytes أو bytearray أو memoryview. وينتظر الجواب 600 ثانية على الأقل، مهما قصرت مهلة timeout في العميل، ما لم تمرّر timeout= إلى الاستدعاء، وقيمة filename الفارغة ترفع ValueError قبل إرسال أي شيء.
المرجع
files.list()المرجع الكاملfiles.list_all()المرجع الكاملfiles.iterate()المرجع الكاملfiles.get()المرجع الكاملfiles.download()المرجع الكاملfiles.list_links()المرجع الكاملfiles.list_all_links()المرجع الكاملfiles.iterate_links()المرجع الكاملfiles.create_link()المرجع الكاملfiles.revoke_link()المرجع الكاملfiles.stats()المرجع الكاملfiles.upload()المرجع الكاملfiles.delete()المرجع الكاملfiles.delete_many()المرجع الكامل