فایل‌ها
`files->list`، `listAll`، `iterate`، `get`، `download`، `listLinks`، `listAllLinks`، `iterateLinks`، `createLink`، `revokeLink`، `revokeAllLinks`، `stats`، `upload`، `delete` و `deleteMany`.
همهٔ متدها
use OpenEmail\Constants\FileKinds;use OpenEmail\Constants\FileSorts; $largest = $client->files->list(kind: FileKinds::PDF, sort: FileSorts::LARGEST, limit: 1); foreach ($largest as $file) { foreach ($client->files->listAllLinks($file['id']) as $link) { echo $link['url'], ' ', $link['downloads'], PHP_EOL; } file_put_contents(basename($file['filename']), $client->files->download($file['id']));} $stats = $client->files->stats();echo $stats['totals']['files'], ' ', $stats['uploaded']['bytes'], PHP_EOL;همهٔ فایل‌هایی که صندوق پستی نگه می‌دارد، پیوست‌های فرستاده و دریافت‌شده و فایل‌هایی که در آن بارگذاری شده‌اند: صفحهٔ «فایل‌ها» در برنامه. download بایت‌ها را به‌صورت یک رشته برمی‌گرداند که file_put_contents آن را بی‌تغییر ذخیره می‌کند. پیوندها همان پیوندهای دانلودی‌اند که فایل با آن‌ها فرستاده شده، همراه با اینکه هرکدام چند بار گرفته شده، و stats زبانهٔ «تحلیل» است.
list، listAll و iterate، q:، kind: و sort: را می‌گیرند، و همچنین direction: (inbound، outbound یا uploaded)، address:، یعنی فایل‌های یک نشانی که بدون توجه به بزرگی و کوچکی حروف مقایسه می‌شود، و since: و until:، یک DateTimeInterface یا یک رشته با قالب ISO 8601. since: لحظهٔ خودش را شامل می‌شود و until: پیش از لحظهٔ خودش می‌ایستد. یک DateTimeInterface به وقت UTC فرستاده می‌شود، و رشته‌ای که فقط یک تاریخ مانند 2026-09-01 دارد نیمه‌شب UTC خوانده می‌شود.
q: در نام فایل و نوع آن جست‌وجو می‌کند. kind: یکی از image، pdf، audio، video یا text است، و sort: یکی از newest (پیش‌فرض)، oldest، largest یا name. OpenEmail\Constants\FileKinds، FileSorts و FileDirections گزینه‌ها را نام می‌برند. list یک OpenEmail\Result\Page برمی‌گرداند، و listAll همهٔ فایل‌ها را در یک آرایه برمی‌گرداند. iterate یک Generator برمی‌گرداند که هر بار یک فایل را yield می‌کند و صفحهٔ بعد را فقط وقتی حلقه به آن نیاز دارد می‌گیرد.
خواندن به files:read نیاز دارد، و بارگذاری، حذف و انتشار یا باطل کردن پیوندها به files:write نیاز دارند، که files:read را هم در بر دارد. به کلیدی که پیش از آنکه فایل‌ها اسکوپ‌های خودشان را داشته باشند ساخته شده، اسکوپ‌های متناظر داده شد. کلیدی که این اسکوپ را ندارد با یک 403 insufficient_scope رد می‌شود، که به‌صورت یک PermissionException پرتاب می‌شود که isScopeMissing() آن true است. کلیدی که به نشانی‌ها یا دامنه‌های خاصی محدود است فقط فایل‌هایی را می‌بیند که به همان‌ها رسیده‌اند، پس فایل‌هایی را که برای کل فضای کاری بارگذاری شده‌اند نمی‌بیند.
download کل فایل را در حافظه نگه می‌دارد، پس فایل‌های بسیار بزرگ را یکی‌یکی بگیرید. پیش از نوشتن، نام را مانند نمونه از basename() بگذرانید، چون از کسی آمده که فایل را فرستاده است.
لینک‌های عمومی
use OpenEmail\Constants\FileDirections; $uploads = $client->files->listAll(direction: FileDirections::UPLOADED, since: new \DateTimeImmutable('2026-09-01T00:00:00Z'));$file = $uploads[0] ?? null; if ($file !== null) { $link = $client->files->createLink($file['id'], domain: 'acme.com'); echo $link['url'], PHP_EOL; $client->files->revokeLink($file['id'], $link['id']);}createLink یک فایل را در یک پیوند دانلود عمومی منتشر می‌کند که بدون ورود باز می‌شود، و پیوند را برمی‌گرداند. پیوند روی میزبان فایل‌های domain: قرار می‌گیرد اگر آن دامنه میزبانی داشته باشد، مانند files.acme.com، وگرنه روی میزبان فایل‌های نشانی‌ای که فایل به آن تعلق دارد، وگرنه روی نشانی API. فایلی که با پیامی آمده یا رفته نخست در فضای ذخیره‌سازی عمومی کپی می‌شود، و یک برنامه یا اسکریپت با یک 422 file_unshareable رد می‌شود که به‌صورت ValidationException پرتاب می‌شود.
هر createLink پیوندی تازه می‌سازد، پس پس از پاسخی گم‌شده هرگز دوباره امتحان نمی‌شود: نخست پیوند را با listLinks جست‌وجو کنید. revokeLink یک پیوند را برای همیشه از کار می‌اندازد، از جمله در ایمیل‌هایی که پیش‌تر رفته‌اند، و آن را با revokedAt تنظیم‌شده برمی‌گرداند. دو بار باطل کردن بی‌خطر است، پس کلاینت آن را مانند یک خواندن دوباره امتحان می‌کند. پیوند ناشناخته یک 404 است که به‌صورت NotFoundException پرتاب می‌شود. revokeAllLinks همهٔ پیوندهای یک فایل را یک‌جا از کار می‌اندازد و تعدادشان را در revoked گزارش می‌کند.
بارگذاری و حذف
$report = "month,sent\n2026-09,1200\n";$upload = $client->files->upload($report, filename: 'report.csv', contentType: 'text/csv'); if ($upload['deletable']) { $client->files->delete($upload['id']);} $logo = $client->files->upload(new \SplFileInfo('logo.svg'));echo $logo['filename'], ' ', $logo['mimeType'], PHP_EOL; $result = $client->files->deleteMany(['file_0c4e7a91d2b84f63a5e19b7d', 'file_6bb640f5b99e47deb758f1f5']); foreach ($result['kept'] as $kept) { echo $kept['filename'], ' ', $kept['reason'], PHP_EOL;}upload بایت‌ها را همان‌طور که هستند، تا 100 MB، با نامی که در filename: آمده ذخیره می‌کند و فایل را برمی‌گرداند. یک ارسال آن را به‌صورت ['fileId' => $upload['id']] در attachments متد emails->send پیوست می‌کند. contentType: را بدهید، یا داده‌ای که نوع خودش را دارد، و هر چیز دیگری به‌صورت application/octet-stream ذخیره می‌شود. نوع هرگز از روی filename: حدس زده نمی‌شود، پس یک رشته از بایت‌ها برای اینکه به‌صورت چیز دیگری ذخیره شود به contentType: نیاز دارد. هرگز دوباره امتحان نمی‌شود، چون تلاش دوم نسخهٔ دومی را ذخیره می‌کرد.
داده یک رشتهٔ بایتی، یک SplFileInfo، یک stream از fopen()، یا یک stream یا فایل بارگذاری‌شدهٔ PSR-7 است. یک SplFileInfo یا streamی که روی یک فایل باز شده به هیچ‌کدام از دو آرگومان نیاز ندارد: نام، نام خودِ فایل است، و نوع از پسوند آن می‌آید وقتی بسته آن را بشناسد، مانند .pdf یا .png. یک بارگذاری Laravel یا Symfony، و یک فایل بارگذاری‌شدهٔ PSR-7، نام و نوعی را که مرورگر فرستاده می‌آورند. یک رشته نامی ندارد، پس رشته‌ای بدون filename: پیش از فرستادن هر چیزی یک InvalidArgumentException پرتاب می‌کند.
یک بارگذاری می‌تواند 600 ثانیه طول بکشد، یا به اندازهٔ timeout کلاینت وقتی آن بیشتر باشد، و timeout: برای یک فراخوانی محدودیت دیگری تعیین می‌کند. کلاینتی که با timeout: 0 ساخته شده به هر اندازه که بارگذاری طول بکشد منتظر می‌ماند.
فقط بارگذاری‌ای را می‌توان حذف کرد که هیچ چیزی به آن وابسته نباشد، و deletable و usage روی هر فایل این را از پیش می‌گویند. delete هر فایل دیگری را با یک 409 file_in_use رد می‌کند که به‌صورت ConflictException پرتاب می‌شود. deleteMany تا 100 شناسه می‌گیرد، هر چه را بتواند حذف می‌کند، و بقیه را در kept، هرکدام با دلیلش، و در missing گزارش می‌کند. هیچ‌کدام دوباره امتحان نمی‌شوند. یک 404 در delete دوم پس از پاسخی گم‌شده یعنی اولی کار کرده است، و deleteMany دوم آن فایل‌ها را در missing گزارش می‌کند.