اعتبارسنجی دسته‌ای

اعتبارسنجی تا 100 آدرس ایمیل در یک درخواست واحد

احراز هویت

کلید API خود را در هدر X-API-Key قرار دهید:

X-API-Key: ml_pv_Ab3Kx9mN2pQ7rT4wL8yD...

اعتبارنامه باید یک اعتبارنامهٔ محصول Validation باشد که کانال Api در آن فعال است.

اعتبارسنجی یک دسته

POST https://api.mail.land/v1/validation/batch

Batch validation request

{
  "emails": [
    "[email protected]",
    "[email protected]",
    "invalid@",
    "[email protected]",
    "[email protected]"
  ],
  "verify_smtp": true
}

فیلد	نوع	پیش‌فرض	توضیحات
`emails`	array	-	آدرس‌های ایمیل برای اعتبارسنجی (الزامی، حداکثر 100)
`verify_smtp`	bool	true	انجام تایید صندوق پستی SMTP

Batch validate

curl -X POST https://api.mail.land/v1/validation/batch \
  -H "X-API-Key: ml_pv_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["[email protected]", "[email protected]", "[email protected]"],
    "verify_smtp": true
  }'

پاسخ

Batch validation response

{
  "total_count": 5,
  "processed_count": 5,
  "successful_count": 5,
  "credits_consumed": 4,
  "free_validations": 1,
  "results": [
    {
      "email": "[email protected]",
      "result": "Deliverable",
      "score": 95,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": false },
      "mx": { "has_mx": true, "records": ["mx.example.com"], "accepts_mail": true },
      "smtp": { "can_connect": true, "is_deliverable": true, "is_catch_all": false, "reachability": "safe" },
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "[email protected]",
      "result": "Deliverable",
      "score": 95,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": false },
      "mx": { "has_mx": true, "records": ["gmail-smtp-in.l.google.com"], "accepts_mail": true },
      "smtp": { "can_connect": true, "is_deliverable": true, "is_catch_all": false, "reachability": "safe" },
      "provider": { "name": "Gmail", "type": "consumer" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "invalid@",
      "result": "Undeliverable",
      "score": 0,
      "syntax": { "is_valid": false, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": false },
      "mx": { "has_mx": false, "records": [], "accepts_mail": false },
      "smtp": null,
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "[email protected]",
      "result": "Undeliverable",
      "score": 10,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": true },
      "role": { "is_role_account": false },
      "mx": { "has_mx": true, "records": ["mx.tempmail.org"], "accepts_mail": true },
      "smtp": null,
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "[email protected]",
      "result": "Deliverable",
      "score": 85,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": true },
      "mx": { "has_mx": true, "records": ["mx.company.com"], "accepts_mail": true },
      "smtp": { "can_connect": true, "is_deliverable": true, "is_catch_all": false, "reachability": "safe" },
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    }
  ]
}

فیلدهای پاسخ

فیلد	نوع	توضیحات
`total_count`	int	تعداد آدرس‌های یکتا در درخواست. موارد تکراری دقیقاً یکسان (حساس به حروف بزرگ و کوچک) پیش از پردازش حذف و فقط یک‌بار اعتبارسنجی می‌شوند، پس این عدد می‌تواند از تعداد ایمیل‌های ارسالی کمتر باشد.
`processed_count`	int	تعداد ایمیل‌های پردازش شده
`successful_count`	int	تعداد اعتبارسنجی‌هایی که بدون خطا تکمیل شدند
`credits_consumed`	int	اعتبارهای کسر شده (اعتبارسنجی‌های پولی)
`free_validations`	int	اعتبارسنجی‌های رایگان (یکبار مصرف، اشتباهات تایپی، خطاهای SMTP)
`results`	array	یک آیتم برای هر آدرس یکتا، به ترتیب اولین‌بار ظاهرشدنش. نتایج را با استفاده از فیلد `email` به ورودی خودتان تطبیق دهید، نه بر اساس موقعیت؛ موارد تکراری در درخواست شما آیتم متناظری نخواهند داشت.

هر آیتم در results همان ساختار پاسخ اعتبارسنجی تکی را دارد.

مصرف اعتبار

اعتبارها قبل از پردازش دسته بررسی می‌شوند. اگر اعتبار کافی برای کل دسته نداشته باشید، درخواست با خطای 402 رد می‌شود.

در داخل دسته، اعتبارسنجی‌های رایگان طبق همان قوانین اعتبارسنجی تکی اعمال می‌شوند:

دامنه‌های یکبار مصرف: رایگان
اشتباهات تایپی با اطمینان بالا (بیش از 90%)، رایگان
خطاهای اتصال SMTP: رایگان

پاسخ جزئیات دقیق را نشان می‌دهد: credits_consumed (صورتحساب شده) + free_validations (صورتحساب نشده) = processed_count.

اعتبارسنجی‌های دسته‌ای تا 10 ایمیل به صورت همزمان در یک درخواست واحد اجرا می‌شوند. این تعادل بین توان عملیاتی و محدودیت‌های نرخ سرور SMTP را برقرار می‌کند. نتایج بدون توجه به ترتیب پردازش، به همان ترتیب آرایه ورودی بازگردانده می‌شوند.

برای لیست‌های بزرگ‌تر از 100 ایمیل، آن‌ها را به چند درخواست دسته‌ای تقسیم کنید. محدودیت همزمانی به ازای هر درخواست اعمال می‌شود: می‌توانید چندین درخواست دسته‌ای را به صورت موازی از سرور خود اجرا کنید.

تاریخچه اعتبارسنجی

تمام اعتبارسنجی‌ها (تکی و دسته‌ای) در تاریخچه اعتبارسنجی شما ثبت می‌شوند:

GET https://api.mail.land/v1/validation/history

پارامتر	نوع	پیش‌فرض	توضیحات
`cursor`	string	-	نشانگر مبهم از `nextCursor` صفحهٔ قبل. برای صفحهٔ اول حذف کنید.
`limit`	int	20	تعداد آیتم‌ها در هر صفحه (حداکثر 100)
`result`	string	-	فیلتر: `Deliverable`، `Risky`، `Unknown`، `Undeliverable`، `Invalid`
`from`	datetime	-	تاریخ شروع
`to`	datetime	-	تاریخ پایان
`search`	string	-	جستجو بر اساس آدرس ایمیل

Validation history response

{
  "items": [
    {
      "email": "u***@example.com",
      "result": "Deliverable",
      "score": 95,
      "is_disposable": false,
      "is_role_account": false,
      "has_valid_mx": true,
      "smtp_deliverable": true,
      "provider": "Unknown",
      "was_cached": false,
      "smtp_verified": true,
      "credit_consumed": true,
      "verified_at": "2026-02-17T12:34:56Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoidmFsaWRhdGlvbjp2ZXJpZmllZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

آدرس‌های ایمیل در تاریخچه برای حفظ حریم خصوصی به صورت جزئی پنهان شده‌اند (مثلا u***@example.com).

آمار اعتبارسنجی

آمار کلی مصرف اعتبارسنجی خود را دریافت کنید:

GET https://api.mail.land/v1/validation/stats

پارامتر	نوع	پیش‌فرض	توضیحات
`from`	datetime	-	تاریخ شروع
`to`	datetime	-	تاریخ پایان

Validation stats response

{
  "total_validations": 450,
  "deliverable": 320,
  "risky": 65,
  "undeliverable": 50,
  "unknown": 15,
  "deliverable_rate": 71.11,
  "risky_rate": 14.44,
  "undeliverable_rate": 11.11,
  "unknown_rate": 3.33,
  "credits_consumed": 380,
  "free_validations": 70
}

محدودیت‌ها

محدودیت	مقدار
حداکثر ایمیل در هر دسته	100
اعتبارسنجی‌های همزمان در هر دسته	10
وقفه SMTP به ازای هر ایمیل	30 ثانیه
حداکثر طول ایمیل	320 کاراکتر

پاسخ‌های خطا

وضعیت	کد	توضیحات
`400`	`INVALID_REQUEST`	حداقل یک ایمیل الزامی است
`400`	`CONTENT_TOO_LARGE`	دسته بیش از 100 ایمیل دارد
`402`	`INSUFFICIENT_CREDITS`	اعتبار کافی برای دسته وجود ندارد

بهترین شیوه‌ها

اعتبارسنجی قبل از واردسازی: قبل از واردسازی لیست‌های مشترکین جدید، اعتبارسنجی دسته‌ای را اجرا کنید تا از افزایش ناگهانی برگشت‌ها جلوگیری شود.
فیلتر بر اساس نتیجه: فقط ایمیل‌های Deliverable را وارد کنید. با ایمیل‌های Risky محتاطانه رفتار کنید و از ایمیل‌های Undeliverable کاملا اجتناب کنید.
بررسی پیشنهادات اشتباه تایپی: وقتی syntax.has_typo برابر true است، syntax.suggestion را قبل از ارسال برای تایید به کاربر نمایش دهید.
استفاده در هنگام ثبت‌نام: ایمیل‌ها را در جریان ثبت‌نام خود با اعتبارسنجی تکی اعتبارسنجی کنید تا از ورود آدرس‌های نامعتبر به سیستم جلوگیری شود.
نظارت بر مصرف اعتبار: /validation/credits را بررسی کنید تا مصرف را پیگیری و قبل از رسیدن به سقف سهمیه، ارتقا را برنامه‌ریزی کنید.

مراحل بعدی

اعتبارسنجی ایمیل تکی: اعتبارسنجی لحظه‌ای برای آدرس‌های تکی
لیست‌های توقف: مدیریت لیست‌های توقف
گرم‌سازی IP: گرم‌سازی دامنه‌ها با لیست‌های تمیز و اعتبارسنجی شده

اعتبارسنجی دسته‌ای

احراز هویتکپی پیوند بخش

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

پاسخکپی پیوند بخش

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

مصرف اعتبارکپی پیوند بخش

همزمانیکپی پیوند بخش

تاریخچه اعتبارسنجیکپی پیوند بخش

آمار اعتبارسنجیکپی پیوند بخش

محدودیت‌هاکپی پیوند بخش

پاسخ‌های خطاکپی پیوند بخش

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

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

در این صفحه