مرجع API

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

تحقق مما إذا تم إدراج مجال أو IP في قوائم البريد الإلكتروني السوداء. استخدم هذا المرجع لاختيار نقطة النهاية المناسبة ومعرفة ما تعيده بالضبط.

العمليات

GET /v1/email/check عرض مرجع API
POST /v1/email/check/bulk عرض مرجع API
GET /v1/email/blacklist عرض مرجع API
GET /v1/email/blacklist/download عرض مرجع API

GET /v1/email/check

العملية: checkEmailBlacklist الوحدات والمصادقة: 1 المصادقة مطلوبة
GET /v1/email/check الرصيد: 1

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

المعامل النوع مطلوب
email string مطلوب
checks string اختياري

حقول الرد

الحقل النوع
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

طلب مثال

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/email/check?email=user%40example.com&checks=disposable%2Crole%2Cfree%2Cmx%2Cdnsbl"
const response = await fetch("https://domscan.net/v1/email/check?email=user%40example.com&checks=disposable%2Crole%2Cfree%2Cmx%2Cdnsbl", {
  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/check?email=user%40example.com&checks=disposable%2Crole%2Cfree%2Cmx%2Cdnsbl",
    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/check?email=user%40example.com&checks=disposable%2Crole%2Cfree%2Cmx%2Cdnsbl", 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/check?email=user%40example.com&checks=disposable%2Crole%2Cfree%2Cmx%2Cdnsbl")
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))

مثال الرد

{
  "email": "[email protected]",
  "domain": "acme-widgets.com",
  "local_part": "support",
  "valid_syntax": true,
  "checks": {
    "disposable": {
      "is_disposable": false,
      "confidence": null
    },
    "role": {
      "is_role": true,
      "role_type": "support"
    },
    "free": {
      "is_free": false,
      "provider": null
    },
    "mx": {
      "has_mx": true,
      "records": [
        "mx1.mailhost-example.net",
        "mx2.mailhost-example.net"
      ]
    },
    "dnsbl": {
      "listed": false,
      "threat_level": "none"
    }
  },
  "risk_score": 20,
  "risk_level": "low",
  "flags": [
    "ROLE_ADDRESS"
  ],
  "checked_at": "2026-10-09T10:15:30.000Z"
}

رموز حالة HTTP

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

POST /v1/email/check/bulk

العملية: bulkEmailCheck الوحدات والمصادقة: 1 المصادقة مطلوبة
POST /v1/email/check/bulk الرصيد: 1/item

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

المعامل النوع مطلوب
dry_run string
القيم المسموحة true
اختياري

معاملات متن الطلب

المعامل النوع مطلوب
emails string[] مطلوب
checks string[]
القيم المسموحة disposablerolefreemxdnsbl
اختياري

حقول الرد

الحقل النوع
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

طلب مثال

curl -X POST "https://domscan.net/v1/email/check/bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "emails": [
    "[email protected]",
    "[email protected]"
  ],
  "checks": [
    "disposable",
    "role",
    "mx"
  ]
}'
const response = await fetch("https://domscan.net/v1/email/check/bulk", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "emails": [
      "[email protected]",
      "[email protected]"
    ],
    "checks": [
      "disposable",
      "role",
      "mx"
    ]
  }),
});
const data = await response.json();
console.log(data);
import os
import requests

response = requests.post(
    "https://domscan.net/v1/email/check/bulk",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "emails": [
            "[email protected]",
            "[email protected]",
        ],
        "checks": [
            "disposable",
            "role",
            "mx",
        ],
    },
)
print(response.json())
package main

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

func main() {
	body := strings.NewReader(`{
	  "emails": [
	    "[email protected]",
	    "[email protected]"
	  ],
	  "checks": [
	    "disposable",
	    "role",
	    "mx"
	  ]
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/email/check/bulk", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	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/check/bulk")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "emails" => [
    "[email protected]",
    "[email protected]"
  ],
  "checks" => [
    "disposable",
    "role",
    "mx"
  ]
})

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))

مثال الرد

{
  "results": [
    {}
  ],
  "summary": {
    "total": 10,
    "disposable": 3,
    "role_based": 1,
    "free_provider": 2,
    "no_mx": 0,
    "dnsbl_listed": 0,
    "high_risk": 3,
    "medium_risk": 1,
    "low_risk": 6
  },
  "checked_at": "2026-08-27T12:00:00Z"
}

رموز حالة HTTP

  • 200 OK
  • 400 طلب غير صالح
  • 401 غير مصرح
  • 402 الدفع مطلوب
  • 409 HTTP 409
  • 422 HTTP 422
  • 429 طلبات كثيرة جداً

GET /v1/email/blacklist

العملية: getEmailBlacklistInfo الوحدات والمصادقة: مجانًا المصادقة مطلوبة
GET /v1/email/blacklist الرصيد: 0

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

المعامل النوع مطلوب
limit integer
الافتراضي 1000
اختياري
offset integer
الافتراضي 0
اختياري
format string
القيم المسموحة jsontxt
الافتراضي json
اختياري
cursor string اختياري

حقول الرد

الحقل النوع
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

طلب مثال

curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/email/blacklist?limit=25&offset=0&format=json"
const response = await fetch("https://domscan.net/v1/email/blacklist?limit=25&offset=0&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?limit=25&offset=0&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?limit=25&offset=0&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?limit=25&offset=0&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": [
    "0-00.usa.cc",
    "0-180.com",
    "0-30-24.com"
  ],
  "total": 91331,
  "offset": 0,
  "limit": 3,
  "metadata": {
    "last_updated": "2026-10-09T03:00:07.499Z",
    "total_domains": 91331,
    "high_confidence_count": 5142,
    "wildcard_count": 0,
    "sources": [
      "disposable-email-domains",
      "fakefilter",
      "mailchecker"
    ],
    "source_count": 8,
    "successful_source_count": 8,
    "failed_source_count": 0,
    "refresh_cadence_hours": 24,
    "refresh_status": "fresh",
    "next_refresh_due": "2026-10-10T03:00:07.499Z",
    "dataset_status": "complete",
    "quality_policy_version": 2,
    "quarantined_domain_count": 0,
    "rejected_domain_count": 0
  }
}

رموز حالة HTTP

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

GET /v1/email/blacklist/download

العملية: downloadEmailBlacklist الوحدات والمصادقة: مجانًا المصادقة مطلوبة
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 طلبات كثيرة جداً

موارد المرجع