# POST /v2/mail/attachments/download

# Mail: Download Attachment

این اندپوینت وظیفه دریافت لینک دانلود فایل‌های پیوست ایمیل را بر عهده دارد.   
برای ایمیل‌های ورودی (Inbox)، از استراتژی **Lazy Download** استفاده می‌شود: فایل ابتدا روی سرور ایمیل خارجی است؛ اگر اولین بار باشد که درخواست می‌شود، فایل دانلود شده، در S3 ذخیره می‌شود و لینک آن در دیتابیس ثبت می‌گردد. در درخواست‌های بعدی، لینک مستقیم S3 بازگردانده می‌شود.

<div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fmail%2Fattach"><div class="endpoint-info"><div>**URL:** `/v2/mail/attachments/download`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** MailController@mailAttachmentsDownload</div><div>**Middleware Stack:** authWithJwt</div></div></div>## Access Control

<div class="api-docs" id="bkmrk-%D8%AF%D8%B3%D8%AA%D8%B1%D8%B3%DB%8C-%D9%85%D8%B9%D8%AA%D8%A8%D8%B1-jwt.">- دسترسی معتبر JWT.

</div>## Body Parameters

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>**(الزامی)** شناسه رکورد پیوست در جدول لوکال (`mail\_attachment.id`).</td></tr><tr><td>service\_id</td><td>integer</td><td>**(الزامی برای Inbox)** شناسه سرویس ایمیل جهت ارتباط با API خارجی.</td></tr><tr><td>mail\_id</td><td>string</td><td>**(الزامی برای Inbox)** شناسه پیام در سرور خارجی (Message ID).</td></tr><tr><td>attach\_id</td><td>string</td><td>**(الزامی برای Inbox)** شناسه پیوست در سرور خارجی.</td></tr><tr><td>branch</td><td>string</td><td>**(الزامی)** نام یا شناسه برنچ جهت ساختن مسیر ذخیره‌سازی فایل در S3 (مثلاً: `uploads/{branch}/mailbox/...`).</td></tr></tbody></table>

</div>## Logic Details

منطق پردازش به شرح زیر است:

<div class="api-docs" id="bkmrk-%D8%A8%D8%A7%D8%B2%DB%8C%D8%A7%D8%A8%DB%8C-%D8%B1%DA%A9%D9%88%D8%B1%D8%AF%3A-%D8%A7%D8%A8%D8%AA%D8%AF%D8%A7">1. **بازیابی رکورد:** ابتدا رکورد پیوست از جدول `mail_attachment` بر اساس `id` خوانده می‌شود.
2. **بررسی جهت (Direction):**
    - **اگر Sent (ارسالی) باشد:** فایل قبلاً هنگام ارسال آپلود شده است. لینک موجود در ستون `storage` مستقیماً بازگردانده می‌شود.
    - **اگر Inbox (دریافتی) باشد:**
        - **بررسی کش (Cache Check):** سیستم چک می‌کند آیا فیلد `storage` مقدار دارد (Not Null)؟ 
            - **بله:** فایل قبلاً دانلود شده است. لینک S3 بازگردانده می‌شود.
            - **خیر (دانلود اولیه):**
                1. یک درخواست به API سرویس‌دهنده ایمیل ارسال می‌شود (با استفاده از `service\_id`, `mail\_id`, `attach\_id`).
                2. محتوای فایل (Base64) دریافت می‌شود.
                3. فایل در S3 (فضای ابری) آپلود می‌شود.
                4. لینک فایل جدید در ستون `storage` رکورد دیتابیس آپدیت می‌شود تا در دفعات بعدی دانلود نشود.
                5. لینک نهایی به کاربر ارسال می‌شود.

</div>## Response Structure

### پاسخ موفق

<div class="api-docs" id="bkmrk-status-code%3A-200-ok-">- **Status Code:** `200 OK` (یا بازگشت آرایه موفق)
- **Body:**```json
    {
      "status": true,
      "time": 1670158000,
      "link": "https://storage.bucket.com/uploads/main/mailbox/2023/05/file.pdf"
    }
    ```

</div>## Flowchart

<div class="api-docs" id="bkmrk-start-%28post-%2Fattachm"><div class="flowchart"><div class="flow-item">Start (POST /attachments/download)</div><div class="flow-arrow">↓</div><div class="flow-item-process">Fetch `mail_attachment` by ID</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Direction?</div><div style="position: relative; left: -180px; top: 20px;"><div class="flow-arrow-label-left" style="top: -30px; left: 80px;">Sent</div><div class="flow-item-success" style="width: 140px; margin-top: 20px;">Return `storage`  
(Existing Link)</div></div><div style="position: relative; left: 180px; top: -100px;"><div class="flow-arrow-label-right" style="top: 80px; left: -30px;">Inbox</div><div class="flow-item-decision" style="margin-top: 110px;">Storage Exists?</div><div style="position: relative; left: -140px; top: 10px;"><div class="flow-arrow-label-left" style="top: -25px; left: 60px;">Yes</div><div class="flow-item-success" style="width: 120px;">Return Link</div></div><div style="position: relative; left: 10px; top: 30px;"><div class="flow-arrow-label-right" style="top: -55px; left: 10px;">No (Null)</div><div class="flow-item-process" style="width: 180px; background-color: #ffe0b2;">**Fetch External API**  
Get Base64 Content</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="width: 180px; background-color: #c8e6c9;">**Upload to S3**  
Update DB `storage`</div><div class="flow-arrow">↓</div><div class="flow-item-success" style="width: 140px;">Return New Link</div></div></div></div></div>