مرجع المطورين
قائمة البريد الإلكتروني السوداء
استكشف توثيق API الخاص بـ قائمة البريد الإلكتروني السوداء، بما في ذلك معلمات الطلب وحقول الاستجابة وأمثلة الشفرة ومعالجة الأخطاء لتكاملات DomScan.
قائمة البريد الإلكتروني السوداء
واجهة API للتحقق من البريد الإلكتروني تكتشف عناوين البريد المؤقتة أو التي تُستخدم لمرة واحدة، والعناوين القائمة على الأدوار، والمزودين المجانيين، وتفحص سمعة النطاق. تحتوي قاعدة البيانات على أكثر من 80,000 نطاق بريد مؤقت مع تقييم ثقة عالٍ ومتوسط ومنخفض. مفيدة لمنع الاحتيال عند الاشتراك وتصفية جودة العملاء المحتملين.
GET
/v1/email/check
معاملات الاستعلام
| المعامل | النوع | Description |
|---|---|---|
| email مطلوب | string | عنوان البريد الإلكتروني للتحقق (مثال: "[email protected]") |
| 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):: احتمالية احتيالية/مؤقتة
طلب مثال
# Full check (all validations)
curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/email/[email protected]"
# Quick disposable check only
curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/email/[email protected]&checks=disposable"
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": "[email protected]"}
)
data = response.json()
if data['risk_level'] == 'high':
print(f"Reject: {data['flags']}")
elif data['checks']['disposable']['is_disposable']:
print("Disposable email detected")
مثال الرد
{
"email": "[email protected]",
"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"] |
حالات الاستخدام
- تنظيف قوائم البريد الإلكتروني قبل حملات التسويق
- التحقق من تسجيلات المستخدمين في الوقت الفعلي
- درجة العملاء المتوقعين بجودة البريد الإلكتروني
- كشف أنماط الاحتيال في التسجيل
طلب مثال
curl -H "X-API-Key: your-api-key" -X POST "https://domscan.net/v1/email/check/bulk" \
-H "Content-Type: application/json" \
-d '{
"emails": [
"[email protected]",
"[email protected]",
"[email protected]"
],
"checks": ["disposable", "role"]
}'
مثال الرد
{
"results": [
{
"email": "[email protected]",
"risk_level": "low",
"risk_score": 10,
"flags": ["FREE_PROVIDER"]
},
{
"email": "[email protected]",
"risk_level": "high",
"risk_score": 80,
"flags": ["DISPOSABLE_DOMAIN"]
},
{
"email": "[email protected]",
"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 من الصفحة السابقة. راجع ترقيم الصفحات. |
| format اختياري | string | json (الافتراضي) أو txt للقائمة النصية العادية |
Description
نزّل قائمة حظر نطاقات البريد المؤقت. مجانية لجميع المستخدمين. استخدم /v1/email/blacklist/download للحصول على القائمة الكاملة كملف قابل للتنزيل.
طلب مثال
# 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
مثال الرد
{
"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
القيم المسموحة
jsontxt
الافتراضي
json
|
اختياري |
حقول الرد
| الحقل | النوع |
|---|---|
domains[] |
string[] |
wildcards[] |
string[] |
metadata |
object |
طلب مثال
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/email/blacklist/download?format=json"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);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())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))
}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))مثال الرد
{
"domains": [
"example.com",
"example.org"
],
"wildcards": [
"example"
],
"metadata": {}
}
رموز حالة HTTP
200OK401غير مصرح429طلبات كثيرة جداً