گزارش ایمیل‌ها

جستجو، فیلتر و بررسی گزارش‌های تحویل دقیق برای هر ایمیل ارسال‌شده از طریق Mail.Land

این صفحه فقط پیام‌های تراکنشی را فهرست می‌کند: ایمیل‌های کمپین و اتوماسیون (شامل پیام‌های سیستمی sys_*) در آن نمی‌آیند. برای تاریخچهٔ ارسال بازاریابی/اتوماسیون از نقطهٔ پایانی گیرندگان کمپین استفاده کنید (به کمپین‌ها نگاه کنید).

فهرست ایمیل‌ها

GET https://api.mail.land/v1/transactional/logs

List emails

curl "https://api.mail.land/v1/transactional/logs?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

پارامترهای پرس‌وجو

پارامتر	نوع	پیش‌فرض	توضیح
`cursor`	string	-	نشانگر مبهم از `nextCursor` صفحهٔ قبل. برای صفحهٔ اول حذف کنید. نشانگر بدشکل یا دست‌کاری‌شده، خطای `400 INVALID_CURSOR` برمی‌گرداند.
`limit`	int	20	تعداد آیتم در هر صفحه
`status`	string	-	فیلتر بر اساس وضعیت (مشاهده زیر)
`search`	string	-	جستجو بر اساس گیرنده، موضوع یا شناسه پیام
`from`	datetime	۳۰ روز پیش	تاریخ شروع
`to`	datetime	اکنون	تاریخ پایان
`refresh`	bool	false	جلوگیری از نمایش صفحه‌ای قدیمی: دیگر حافظهٔ پنهانی برای شمارش وجود ندارد که دور زده شود

فیلترهای وضعیت

مقدار	تطابق
`queued`	در انتظار در صف
`sent`	پذیرفته‌شده توسط MTA
`deferred` یا `retrying`	تاخیر موقت
`delivered`	تحویل موفق
`bounced`	برگشت سخت
`failed`	خطای سیستم یا برگشت مدیریتی
`opened`	گیرنده ایمیل را باز کرده
`clicked`	گیرنده روی لینک کلیک کرده
`complained`	گیرنده شکایت اسپم ثبت کرده

Email logs response

{
  "items": [
    {
      "messageId": "t_a1b2c3d4e5f6",
      "recipient": "[email protected]",
      "subject": "Your order has shipped",
      "status": "delivered",
      "sentAt": "2026-02-17T12:34:56Z",
      "deliveredAt": "2026-02-17T12:34:58Z",
      "openedAt": "2026-02-17T13:15:00Z",
      "clickedAt": null,
      "bounceReason": null,
      "openCount": 2,
      "clickCount": 0
    },
    {
      "messageId": "t_d4e5f6a1b2c3",
      "recipient": "[email protected]",
      "subject": "Invoice #1234",
      "status": "bounced",
      "sentAt": "2026-02-17T12:30:00Z",
      "deliveredAt": null,
      "openedAt": null,
      "clickedAt": null,
      "bounceReason": "550 5.1.1 Mailbox not found",
      "openCount": 0,
      "clickCount": 0
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

اولویت وضعیت

فیلد status بالاترین اولویت رویداد برای هر ایمیل را نشان می‌دهد:

complained (بالاترین)
clicked
opened
وضعیت تحویل: queued → sent → deferred → delivered → bounced → failed

برای مثال، اگر ایمیلی تحویل شده و سپس باز شده باشد، وضعیت opened نمایش داده می‌شود.

به طور پیش‌فرض، بازه زمانی ۳۰ روزه برای عملکرد اعمال می‌شود. پارامتر جستجو بر اساس ایمیل گیرنده، موضوع یا شناسه پیام فیلتر می‌کند (غیر حساس به حروف بزرگ و کوچک).

آمار گزارش

آمار تجمیعی برای گزارش‌های ایمیل خود دریافت کنید:

GET https://api.mail.land/v1/transactional/logs/stats

Get log stats

curl "https://api.mail.land/v1/transactional/logs/stats" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

پارامتر	نوع	پیش‌فرض	توضیح
`from`	datetime	۷ روز پیش	تاریخ شروع
`to`	datetime	اکنون	تاریخ پایان
`emailType`	int	-	`0` = تراکنشی، `1` = بازاریابی. حذف‌کردنِ آن، همهٔ انواع ایمیل را پوشش می‌دهد: برخلاف «فهرست ایمیل‌ها» در بالا که فقط تراکنشی را نشان می‌دهد.
`refresh`	bool	false	دور زدن حافظه پنهان

Log stats response

{
  "total": 4750,
  "accepted": 4750,
  "sent": 4700,
  "delivered": 4680,
  "opened": 1498,
  "clicked": 195,
  "bounced": 38,
  "complained": 1,
  "failed": 12,
  "queued": 20,
  "deliveryRate": 99.57,
  "openRate": 32.01,
  "clickRate": 13.02,
  "bounceRate": 0.81,
  "complaintRate": 0.021,
  "source": "clickhouse",
  "queryTimeMs": 32
}

محاسبات نرخ:

نرخ	فرمول
`deliveryRate`	`delivered / sent * 100`
`openRate`	`opened / delivered * 100`
`clickRate`	`clicked / delivered * 100`
`bounceRate`	`bounced / sent * 100`
`complaintRate`	`complained / sent * 100` (۳ رقم اعشار)

هدرهای پاسخ وضعیت حافظه پنهان را نشان می‌دهند:

هدر	مقادیر
`X-Cache`	`HIT`، `MISS` یا `FRESH`
`X-Stats-Source`	`cache` یا `clickhouse`
`Cache-Control`	همیشه `no-store, no-cache, must-revalidate`

جزئیات ایمیل

جزئیات کامل یک ایمیل خاص، از جمله خط زمانی رویداد را دریافت کنید:

GET https://api.mail.land/v1/transactional/logs/{messageId}

Get email detail

curl https://api.mail.land/v1/transactional/logs/t_a1b2c3d4e5f6 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Email detail response

{
  "messageId": "t_a1b2c3d4e5f6",
  "recipient": "[email protected]",
  "fromEmail": "[email protected]",
  "subject": "Your order has shipped",
  "status": "opened",
  "sentAt": "2026-02-17T12:34:56Z",
  "deliveredAt": "2026-02-17T12:34:58Z",
  "openedAt": "2026-02-17T13:15:00Z",
  "clickedAt": null,
  "createdAt": "2026-02-17T12:34:55Z",
  "bounceReason": null,
  "bounceCategory": null,
  "ipAddress": null,
  "retryCount": 0,
  "smtpResponse": "250 2.0.0 OK",
  "openCount": 2,
  "clickCount": 0,
  "htmlContent": "<html>...</html>",
  "textContent": "Your order has shipped...",
  "events": [
    {
      "eventType": "delivered",
      "timestamp": "2026-02-17T12:34:58Z",
      "ipAddress": null,
      "userAgent": null,
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": "250 2.0.0 OK",
      "deviceType": null,
      "browser": null,
      "country": null,
      "city": null
    },
    {
      "eventType": "opened",
      "timestamp": "2026-02-17T13:15:00Z",
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": null,
      "deviceType": "desktop",
      "browser": "Chrome",
      "country": "US",
      "city": "San Francisco"
    },
    {
      "eventType": "opened",
      "timestamp": "2026-02-17T14:30:00Z",
      "ipAddress": "203.0.113.45",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)",
      "linkUrl": null,
      "bounceType": null,
      "bounceReason": null,
      "smtpResponse": null,
      "deviceType": "mobile",
      "browser": "Safari",
      "country": "US",
      "city": "San Francisco"
    }
  ]
}

آرایه events از ClickHouse تامین شده و بر اساس زمان مرتب شده است. اگر ClickHouse به طور موقت در دسترس نباشد، جزئیات ایمیل همچنان از PostgreSQL برگردانده می‌شود اما events آرایه‌ای خالی خواهد بود.

فیلدهای رویداد

فیلد	توضیح
`eventType`	`delivered`، `opened`، `clicked`، `bounced`، `complained`، و همچنین `accepted`، `sent`، `deferred`، `admin_bounce`، `oob_bounce`، `expired`
`timestamp`	زمان وقوع رویداد (UTC)
`ipAddress`	IP مشتری (برای بازشدن‌ها/کلیک‌ها)
`userAgent`	رشته عامل کاربر مشتری
`linkUrl`	URL کلیک‌شده (برای رویدادهای `clicked`)
`bounceType`	`hard`، `soft` یا `unknown` (برای رویدادهای `bounced`)
`bounceReason`	پاسخ SMTP (برای رویدادهای `bounced`)
`smtpResponse`	پاسخ سرور راه دور (برای رویدادهای `delivered`)
`deviceType`	`desktop`، `mobile` یا `tablet`
`browser`	نام مرورگر (Chrome، Safari، Firefox و غیره)
`country`	کد کشور ISO
`city`	نام شهر

تلاش مجدد برای ایمیل ناموفق

تحویل ایمیل برگشت‌خورده یا ناموفق را دوباره امتحان کنید:

POST https://api.mail.land/v1/transactional/logs/{messageId}/retry

Retry failed email

curl -X POST https://api.mail.land/v1/transactional/logs/t_a1b2c3d4e5f6/retry \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

پیام باید در وضعیت Bounced یا Failed باشد و گیرنده نباید در لیست حذف باشد.

وضعیت	کد	توضیح
`200`	-	تلاش مجدد پذیرفته شد
`400`	`INVALID_REQUEST`	ایمیل برگشت‌خورده یا ناموفق نیست
`400`	`RECIPIENT_SUPPRESSED`	گیرنده در لیست حذف است
`404`	`RESOURCE_NOT_FOUND`	پیام یافت نشد: نه `EMAIL_NOT_FOUND`
`422`	`DOMAIN_NOT_VERIFIED`	دامنهٔ ارسال دیگر تأیید نشده است
`429`	`MARKETING_PAUSED`	ارسال بازاریابی برای این فضای کاری فعلاً متوقف است
`422`	`RETRY_ATTACHMENTS_UNAVAILABLE`	پیام پیوست داشت که دیگر قابل بازیابی نیست؛ به‌جای آن دوباره با پیوست‌ها ارسال کنید
`422`	`RETRY_ATTACHMENTS_UNKNOWN`	پیام پیش از ثبت پیوست‌ها ارسال شده و تلاش دوباره نمی‌تواند پیوست‌ها را تضمین کند؛ به‌جای آن دوباره ارسال کنید
`429`	`PLATFORM_CAPACITY_PROTECTION`	ارسال جدید برای محافظت از ظرفیت پلتفرم کوتاه‌مدت متوقف است؛ چیزی تغییر نکرد، کمی بعد دوباره تلاش کنید
`503`	`RETRY_ATTACHMENT_STORAGE_UNAVAILABLE`	پیوست‌ها در این لحظه خوانده نشدند؛ چیزی تغییر نکرد، کمی بعد دوباره تلاش کنید

تلاش مجدد یک کار ایمیل جدید با محتوای اصلی ایجاد می‌کند و آن را برای تحویل در صف قرار می‌دهد. نسخه‌های ارسال‌شدهٔ دوباره بدون ردیابی بازشدن/کلیک ارسال می‌شوند.

مراحل بعدی

نمای کلی تحلیل‌ها: خلاصه رویدادهای تجمیعی و نرخ‌ها
تحلیل‌های پیشرفته: تفکیک جغرافیایی، دستگاه و زمان روز
برگشت‌ها: مدیریت برگشت و تلاش مجدد

گزارش ایمیل‌ها

فهرست ایمیل‌هاکپی پیوند بخش

پارامترهای پرس‌وجوکپی پیوند بخش

فیلترهای وضعیتکپی پیوند بخش

اولویت وضعیتکپی پیوند بخش

آمار گزارشکپی پیوند بخش

جزئیات ایمیلکپی پیوند بخش

فیلدهای رویدادکپی پیوند بخش

تلاش مجدد برای ایمیل ناموفقکپی پیوند بخش

مراحل بعدیکپی پیوند بخش

در این صفحه