Skip to main content
#P1699

GET /v2/mail/{type}/list

Mail: Get Mailbox List

این اندپوینت چندمنظوره برای دریافت لیست ایمیل‌ها بر اساس دسته‌بندی‌های مختلف استفاده می‌شود.
بسته به پارامتر type در آدرس، سیستم می‌تواند صندوق ورودی، صندوق ارسال، پیش‌نویس‌ها، یا ایمیل‌های فیلتر شده بر اساس تگ و لیبل را بازگرداند.

Request Overview

URL: /v2/mail/{type}/list
Method: GET
Controller: MailController@mailBox
Middleware Stack: authWithJwt

Access Control

  • دسترسی معتبر JWT.

Path Parameters

Field Description
type نوع صندوق یا فیلتر مورد نظر. مقادیر مجاز:
  • inbox (صندوق ورودی)
  • sent (صندوق ارسال)
  • Types: draft, trash, spam, outbox
  • Tags: starred, important
  • Labels: tickets, personal, work, finance, ...

Query Parameters

Field Type Description
address_id integer (الزامی) شناسه آدرس ایمیل در دیتابیس (`mail_address.id`) که قصد دریافت ایمیل‌های آن را دارید.
service_id integer (فقط برای Inbox) جهت سینک کردن ایمیل‌ها و ارسال به جاب صف (SnailJob).

Logic Details

منطق این متد بر اساس type به سه شاخه اصلی تقسیم می‌شود:

  1. حالت Inbox (صندوق ورودی):
    • ابتدا یک جاب (Job) برای همگام‌سازی ایمیل‌ها با سرویس‌دهنده خارجی (Liara Mail) در صف snailJob دیسپچ می‌شود (با تاخیر ۱۰ دقیقه).
    • از جدول mail_inbox کوئری گرفته می‌شود (شرط: recipient و status=1).
    • تعداد پیوست‌ها (Attachments) محاسبه شده و خروجی فرمت‌دهی می‌شود.
  2. حالت Sent (صندوق ارسال):
    • از جدول mail_sent کوئری گرفته می‌شود (شرط: from و status=1).
    • لیست گیرندگان (`recipients`) در خروجی قرار می‌گیرد.
  3. حالت‌های فیلتر (Type/Tag/Label):
    • سیستم ابتدا تشخیص می‌دهد که type درخواستی جزو کدام دسته است (Type, Tag یا Label).
    • سپس هر دو جدول mail_inbox و mail_sent را جستجو می‌کند.
    • این یعنی اگر شما دنبال تگ important باشید، هم ایمیل‌های دریافتی و هم ایمیل‌های ارسالی که این تگ را دارند بازگردانده می‌شوند.

Response Structure

پاسخ موفق

خروجی آرایه‌ای از اشیاء ایمیل است. بسته به نوع (دریافتی/ارسالی) فیلد sender یا recipients وجود خواهد داشت.

  • Status Code: 200 OK
  • Body: 
    {
  "status": true,
  "time": 1670156000,
  "data": [
    {
      "id": 105,
      "direction": "inbox",
      "sender": "client@gmail.com",
      "sender_name": "John Doe",
      "subject": "Project Update",
      "avatar": false,
      "attachment": 2, // Count of attachments
      "type": false,
      "tag": "starred",
      "label": "work",
      "created_at": "2023-05-20 10:00:00",
      "read_at": null
    },
    {
      "id": 88,
      "direction": "sent",
      "recipients": "boss@company.com", // Specific to sent items
      "subject": "Weekly Report",
      "attachment": 0,
      "type": false,
      "tag": false,
      "label": "finance",
      "created_at": "2023-05-19 14:00:00"
    }
  ]
}

Flowchart

Start (GET /mail/{type}/list)
↓
Check {type}
Inbox
Dispatch Job
Sync Mail (10m delay)
↓
Query `mail_inbox`
Where recipient = ID
Sent
Query `mail_sent`
Where from = ID
Other (Tag/Label)
Dual Query
Query `mail_inbox` AND `mail_sent`
Where key = {type}
↓
Format & Merge
Calculate Attachments Count
Standardize Fields
↓
Return JSON Data
Back to top