الملفات
`files.list` و`list_all` و`iterate` و`get` و`download` و`list_links` و`list_all_links` و`iterate_links` و`create_link` و`revoke_link` و`stats` و`upload` و`delete` و`delete_many`.
كل الدوالّ
page = client.files.list(kind: "pdf", sort: "largest")file = page.items.first links = client.files.list_all_links(file[:id])p links.map { |link| [link[:url], link[:downloads]] } stats = client.files.statsputs stats.dig(:totals, :files), stats.dig(:uploaded, :bytes) File.binwrite(file[:filename], client.files.download(file[:id]))كل ملف يحتفظ به صندوق البريد، من المرفقات المُرسلة والمُستلمة والملفات المرفوعة إليه: أي صفحة الملفات في التطبيق. يعيد download البايتات في صورة String ثنائي، يحفظه File.binwrite دون تغيير. والروابط هي روابط التنزيل التي خرج بها الملف، مع عدد مرات جلب كل منها، وstats هو تبويب التحليلات.
يأخذ list وlist_all وiterate الوسائط q: وkind: وsort:، وكذلك direction: (inbound أو outbound أو uploaded)، وaddress: أي ملفات عنوان واحد مع مقارنة لا تراعي حالة الأحرف، وsince: وuntil: بوصفهما Time أو DateTime أو String بصيغة ISO 8601. ويشمل since: لحظته ويتوقف until: قبل لحظته. ويُرسَل Date في Ruby كتاريخ مجرد، تقرؤه هذه القائمة على أنه منتصف الليل UTC.
يبحث q: في اسم الملف ونوعه. وقيمة kind: هي image أو pdf أو audio أو video أو text، وقيمة sort: هي newest، وهي الافتراضية، أو oldest أو largest أو name. ويسمّي OpenEmail::FILE_KINDS وOpenEmail::FILE_SORTS وOpenEmail::FILE_DIRECTIONS الخيارات. ويعيد list صفحة OpenEmail::Page واحدة، ويعيد list_all كل الملفات في Array واحدة. ويمرّر iterate كل ملف إلى كتلة ولا يجلب الصفحة التالية إلا حين تحتاجها الحلقة. ودون كتلة يعيد Enumerator.
تحتاج القراءة إلى files:read، ويحتاج الرفع والحذف ونشر الروابط أو سحبها إلى files:write، الذي يشمل files:read. والمفتاح الذي أُنشئ قبل أن تصير للملفات نطاقات خاصة بها مُنح النطاقات المقابلة. والمفتاح الذي ينقصه النطاق يُرفض بـ 403 insufficient_scope، وتكون قيمة scope_missing? في الخطأ true. والمفتاح المقصور على عناوين أو نطاقات بعينها لا يرى إلا الملفات التي وصلت إليها، فلا يرى الملفات المرفوعة لمساحة العمل كلها.
يحتفظ download بالملف كله في الذاكرة، فاجلب الملفات الكبيرة جدًا واحدًا تلو الآخر.
الروابط العامة
uploads = client.files.list_all(direction: "uploaded", since: Time.utc(2026, 9, 1))file = uploads.first link = client.files.create_link(file[:id], domain: "acme.com")puts link[:url] client.files.revoke_link(file[:id], link[:id])ينشر create_link ملفًا على رابط تنزيل عام يُفتح دون تسجيل دخول، ويعيد الرابط. ويقع الرابط على مضيف الملفات لـ domain: حين يكون لذلك النطاق مضيف، مثل files.acme.com، وإلا فعلى مضيف الملفات للعنوان الذي ينتمي إليه الملف، وإلا فعلى عنوان API. والملف الذي وصل أو خرج مع رسالة يُنسخ أولًا إلى تخزين عام، ويُرفض البرنامج أو السكربت بـ 422 file_unshareable، يُرفع في صورة OpenEmail::ValidationError.
كل create_link يصنع رابطًا جديدًا، لذا لا تُعاد محاولته أبدًا بعد ضياع الجواب: ابحث عن الرابط أولًا عبر list_links. ويوقف revoke_link الرابط نهائيًا، بما في ذلك في البريد الذي خرج من قبل، ويعيده مع ضبط revokedAt. وسحب الرابط مرتين آمن، فيعيد الـ gem محاولته كما يفعل مع القراءة. والرابط غير المعروف يعطي 404، يُرفع في صورة OpenEmail::NotFoundError.
الرفع والحذف
upload = client.files.upload(File.binread("report.pdf"), filename: "report.pdf", content_type: "application/pdf")client.files.delete(upload[:id]) if upload[:deletable] invoice = client.files.upload(Pathname("invoice.pdf"))puts invoice[:filename], invoice[:mimeType] result = client.files.delete_many(["file_0c4e7a91d2b84f63a5e19b7d", "file_6bb640f5b99e47deb758f1f5"])result[:kept].each { |kept| puts "#{kept[:filename]} #{kept[:reason]}" }يخزّن upload البايتات كما هي، حتى 100 ميغابايت، بالاسم الوارد في filename:، ويعيد الملف. ويرفقه الإرسال بوصفه {fileId: upload[:id]} في attachments الخاصة بـ emails.send. مرّر content_type:، أو بايتات تحمل نوعها بنفسها، وكل ما عدا ذلك يُخزَّن بوصفه application/octet-stream. ولا تُعاد محاولته أبدًا، لأن المحاولة الثانية ستخزّن نسخة ثانية.
البايتات String ثنائي أو IO أو Pathname. ولا يحتاج Pathname أو File إلى أيٍّ من الوسيطين المسمّيين: فالاسم هو اسم الملف نفسه، والنوع يأتي من امتداده حين يعرفه الـ gem، مثل .pdf أو .png. والملف المرفوع في Rails يجلب معه original_filename وcontent_type الخاصين به. أما البايتات المجردة فلا تحمل اسمًا، فيرفع String أو StringIO دون filename: الخطأ ArgumentError قبل إرسال أي شيء.
قد يستمر الرفع 600 ثانية، أو مدة timeout الخاصة بالعميل إن كانت أطول، ويضبط timeout: حدًا آخر لاستدعاء واحد. والعميل المبني مع timeout: 0 ينتظر ما يستغرقه الرفع مهما طال.
لا يُحذف إلا ملف مرفوع لا يعتمد عليه شيء، ويذكر deletable وusage في كل ملف ذلك مسبقًا. ويرفض delete أي ملف آخر بـ 409 file_in_use، يُرفع في صورة OpenEmail::ConflictError. ويأخذ delete_many حتى 100 معرّف، ويحذف ما يستطيع، ويبلّغ عن الباقي في kept، كلٌّ مع سببه، وفي missing. ولا تُعاد محاولة أيٍّ منهما. وخطأ 404 في delete ثانٍ بعد ضياع الجواب يعني أن الأول نجح، وdelete_many الثاني يبلّغ عن تلك الملفات في missing.