مرجع المطورين

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

استكشف توثيق 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

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