> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/ar/docs/email-blacklist

# قائمة البريد الإلكتروني السوداء

استكشف توثيق API الخاص بـ قائمة البريد الإلكتروني السوداء، بما في ذلك معلمات الطلب وحقول الاستجابة وأمثلة الشفرة ومعالجة الأخطاء لتكاملات DomScan.

واجهة API للتحقق من البريد الإلكتروني تكتشف عناوين البريد المؤقتة أو التي تُستخدم لمرة واحدة، والعناوين القائمة على الأدوار، والمزودين المجانيين، وتفحص سمعة النطاق. تحتوي قاعدة البيانات على أكثر من 80,000 نطاق بريد مؤقت مع تقييم ثقة عالٍ ومتوسط ومنخفض. مفيدة لمنع الاحتيال عند الاشتراك وتصفية جودة العملاء المحتملين.

GET /v1/email/check

#### معاملات الاستعلام

| المعامل | النوع | Description |
| --- | --- | --- |
| email مطلوب | string | عنوان البريد الإلكتروني للتحقق (مثال: "user@tempmail.com") |
| checks اختياري | string | الفحوصات المفصولة بفواصل للتشغيل: `disposable` و `role` و `free` و `mx` و `dnsbl`. افتراضي: الكل |

#### الفحوصات المتاحة

| تحقق | Description | نقاط المخاطر |
| --- | --- | --- |
| `disposable` | التحقق من 80K+ قاعدة بيانات مجالات قابلة للتجاهل | +80 |
| `role` | الكشف عن عناوين مستندة إلى الأدوار (admin@، support@، إلخ) | +20 |
| `free` | تحديد مزودي البريد الإلكتروني المجانيين (gmail، yahoo، إلخ) | +10 |
| `mx` | التحقق من وجود سجلات MX للنطاق | +50 (إذا لم يوجد) |
| `dnsbl` | تحقق من النطاق مقابل قوائم حظر DNS (Spamhaus، إلخ) | +15-60 |

#### مستويات المخاطرة

- **منخفضة (0-39)::** آمن للقبول

- **متوسطة (40-69)::** يوصى بالمراجعة

- **عالية (70-100)::** احتمالية احتيالية/مؤقتة

#### طلب مثال

```bash
# Full check (all validations)
curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/email/check?email=user@tempmail.com"

# Quick disposable check only
curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/email/check?email=user@gmail.com&checks=disposable"
```

```python
import requests

domscan = requests.Session()
domscan.headers.update({"X-API-Key": "your-api-key"})

response = domscan.get(
    "https://domscan.net/v1/email/check",
    params={"email": "user@tempmail.com"}
)
data = response.json()

if data['risk_level'] == 'high':
    print(f"Reject: {data['flags']}")
elif data['checks']['disposable']['is_disposable']:
    print("Disposable email detected")
```

#### مثال الرد

```json
{
  "email": "user@tempmail.com",
  "domain": "tempmail.com",
  "local_part": "user",
  "valid_syntax": true,
  "checks": {
    "disposable": {
      "is_disposable": true,
      "confidence": "high"
    },
    "role": {
      "is_role": false,
      "role_type": null
    },
    "free": {
      "is_free": false,
      "provider": null
    },
    "mx": {
      "has_mx": true,
      "records": ["mx.tempmail.com"]
    },
    "dnsbl": {
      "listed": false,
      "threat_level": "none"
    }
  },
  "risk_score": 80,
  "risk_level": "high",
  "flags": ["DISPOSABLE_DOMAIN"],
  "checked_at": "2025-01-15T12:00:00Z"
}
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `email` | string |
| `domain` | string |
| `local_part` | string |
| `valid_syntax` | boolean |
| `checks` | object |
| `checks.disposable` | object |
| `checks.disposable.is_disposable` | boolean |
| `checks.disposable.confidence` | string \| null |
| `checks.disposable.matched_pattern` | string |
| `checks.role` | object |
| `checks.role.is_role` | boolean |
| `checks.role.role_type` | string \| null |
| `checks.free` | object |
| `checks.free.is_free` | boolean |
| `checks.free.provider` | string \| null |
| `checks.mx` | object |
| `checks.mx.has_mx` | boolean \| null |
| `checks.mx.records[]` | string[] |
| `checks.mx.null_mx` | boolean |
| `checks.dnsbl` | object |
| `checks.dnsbl.domain` | string |
| `checks.dnsbl.ip` | string |
| `checks.dnsbl.listed` | boolean |
| `checks.dnsbl.lists[]` | object[] |
| `checks.dnsbl.lists[]` | object |
| `checks.dnsbl.lists[].name` | string |
| `checks.dnsbl.lists[].listed` | boolean |
| `checks.dnsbl.lists[].status` | string |
| `checks.dnsbl.lists[].code` | string |
| `checks.dnsbl.lists[].meaning` | string |
| `checks.dnsbl.lists[].unknown_reason` | string |
| `checks.dnsbl.lists_unknown` | integer |
| `checks.dnsbl.threat_level` | string |
| `checks.dnsbl.check_type` | string |
| `checks.dnsbl.checked_at` | string |
| `risk_score` | integer |
| `risk_level` | string |
| `flags[]` | string[] |
| `checked_at` | string |

POST /v1/email/check/bulk

#### نص الطلب

| المعامل | النوع | Description |
| --- | --- | --- |
| emails مطلوب | string[] | مصفوفة من عناوين البريد الإلكتروني للتحقق (الحد الأقصى 100 لكل طلب) |
| checks اختياري | string[] | الفحوصات التي يتم تشغيلها: ["disposable"، "role"، "free"، "mx"، "dnsbl"] |

#### حالات الاستخدام

- تنظيف قوائم البريد الإلكتروني قبل حملات التسويق

- التحقق من تسجيلات المستخدمين في الوقت الفعلي

- درجة العملاء المتوقعين بجودة البريد الإلكتروني

- كشف أنماط الاحتيال في التسجيل

#### طلب مثال

```bash
curl -H "X-API-Key: your-api-key" -X POST "https://domscan.net/v1/email/check/bulk" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "user@gmail.com",
      "test@tempmail.org",
      "admin@company.com"
    ],
    "checks": ["disposable", "role"]
  }'
```

#### مثال الرد

```json
{
  "results": [
    {
      "email": "user@gmail.com",
      "risk_level": "low",
      "risk_score": 10,
      "flags": ["FREE_PROVIDER"]
    },
    {
      "email": "test@tempmail.org",
      "risk_level": "high",
      "risk_score": 80,
      "flags": ["DISPOSABLE_DOMAIN"]
    },
    {
      "email": "admin@company.com",
      "risk_level": "medium",
      "risk_score": 20,
      "flags": ["ROLE_ADDRESS"]
    }
  ],
  "summary": {
    "total": 3,
    "disposable": 1,
    "role_based": 1,
    "free_provider": 1,
    "high_risk": 1,
    "medium_risk": 1,
    "low_risk": 1
  },
  "checked_at": "2025-01-15T12:00:00Z"
}
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `results[]` | object[] |
| `results[]` | object |
| `summary` | object |
| `summary.total` | integer |
| `summary.disposable` | integer |
| `summary.role_based` | integer |
| `summary.free_provider` | integer |
| `summary.no_mx` | integer |
| `summary.dnsbl_listed` | integer |
| `summary.high_risk` | integer |
| `summary.medium_risk` | integer |
| `summary.low_risk` | integer |
| `checked_at` | string |

GET /v1/email/blacklist

#### معاملات الاستعلام

| المعامل | النوع | Description |
| --- | --- | --- |
| limit اختياري | number | عدد النطاقات التي سيتم إرجاعها (الافتراضي: 1000، الحد الأقصى: 10000) |
| offset اختياري | number | إزاحة الترقيم (الافتراضي: 0) |
| cursor اختياري | string | قيمة `next_cursor` من الصفحة السابقة. راجع [ترقيم الصفحات](https://domscan.net/docs/response-format#pagination). |
| format اختياري | string | `json` (الافتراضي) أو `txt` للقائمة النصية العادية |

#### Description

نزّل قائمة حظر نطاقات البريد المؤقت. مجانية لجميع المستخدمين. استخدم `/v1/email/blacklist/download` للحصول على القائمة الكاملة كملف قابل للتنزيل.

#### طلب مثال

```bash
# Get first 1000 domains as JSON
curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/email/blacklist"

# Get as plain text for firewall rules
curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/email/blacklist?format=txt&limit=5000"

# Download complete blacklist
curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/email/blacklist/download" -o disposable.json
```

#### مثال الرد

```json
{
  "domains": [
    "tempmail.com",
    "guerrillamail.com",
    "10minutemail.com",
    "mailinator.com",
    "..."
  ],
  "total": 85432,
  "offset": 0,
  "limit": 1000,
  "metadata": {
    "last_updated": "2025-01-15T00:00:00Z",
    "total_domains": 85432,
    "high_confidence_count": 12500,
    "wildcard_count": 234,
    "sources": [
      "disposable-email-domains",
      "ivolo/disposable-email-domains"
    ]
  }
}
```

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `has_more` | boolean |
| `next_cursor` | string \| null |
| `domains[]` | string[] |
| `total` | integer |
| `offset` | integer |
| `limit` | integer |
| `metadata` | object |
| `metadata.last_updated` | string |
| `metadata.total_domains` | integer |
| `metadata.high_confidence_count` | integer |
| `metadata.wildcard_count` | integer |
| `metadata.sources[]` | string[] |
| `metadata.source_count` | integer |
| `metadata.successful_source_count` | integer |
| `metadata.failed_source_count` | integer |
| `metadata.refresh_cadence_hours` | integer |
| `metadata.refresh_status` | string |
| `metadata.next_refresh_due` | string |
| `metadata.dataset_status` | string |
| `metadata.quality_policy_version` | integer \| null |
| `metadata.quarantined_domain_count` | integer |
| `metadata.rejected_domain_count` | integer |

GET /v1/email/blacklist/download الرصيد: 0

#### معاملات الاستعلام

| المعامل | النوع | مطلوب |
| --- | --- | --- |
| format | string القيم المسموحة `json`, `txt` الافتراضي `json` | اختياري |

#### حقول الرد

| الحقل | النوع |
| --- | --- |
| `domains[]` | string[] |
| `wildcards[]` | string[] |
| `metadata` | object |

#### طلب مثال

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/email/blacklist/download?format=json"
```

```javascript
const response = await fetch("https://domscan.net/v1/email/blacklist/download?format=json", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/email/blacklist/download?format=json",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/email/blacklist/download?format=json", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Status, string(data))
}
```

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/email/blacklist/download?format=json")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.pretty_generate(JSON.parse(response.body))
```

#### مثال الرد

```json
{
  "domains": [
    "example.com",
    "example.org"
  ],
  "wildcards": [
    "example"
  ],
  "metadata": {}
}
```

#### رموز حالة HTTP

- `200` OK
- `401` غير مصرح
- `429` طلبات كثيرة جداً
