التحقق من بريد إلكتروني واحد
تحققوا من عنوان بريد إلكتروني واحد في الوقت الفعلي. تتضمن الاستجابة تفاصيل التوقيت، ويعتمد زمن الاستجابة على خوادم البريد البعيدة وظروف الشبكة.
نقطة النهاية
POST
https://verimails.com/api/verify/single
الطلب
الترويسات
| الترويسة | مطلوب | القيمة |
|---|---|---|
Authorization | نعم | Bearer YOUR_API_KEY |
Content-Type | نعم | application/json |
النص
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
email | string | نعم | عنوان البريد الإلكتروني المراد التحقق منه |
json
{
"email": "user@example.com"
}
الاستجابة
حقول الاستجابة
| الحقل | النوع | الوصف |
|---|---|---|
email | string | عنوان البريد الإلكتروني الذي تم التحقق منه |
status | string | نتيجة التحقق: valid, invalid, risky, unknown، أو disposable |
safe_to_send | boolean | ما إذا كانت VeriMails توصي بالإرسال إلى هذا العنوان. تكون true فقط عندما status تساوي valid. |
confidence_score | number | مستوى الثقة الإجمالي لنتيجة التحقق. |
domain | string | النطاق المستخرج من عنوان البريد الإلكتروني. |
is_catch_all | boolean | ما إذا كان النطاق يقبل البريد على نطاق واسع، مما يصعّب تأكيد صندوق البريد الفردي. |
is_disposable | boolean | ما إذا كان العنوان يستخدم مزوّد بريد مؤقت. |
is_role_based | boolean | ما إذا كان العنوان صندوقًا وظيفيًا مثل info@ أو support@. |
is_free | boolean | ما إذا كان النطاق مزوّد بريد مجاني. |
verification_time_ms | integer | زمن المعالجة بالمللي ثانية. |
مثال على الاستجابة: بريد إلكتروني صالح
json
{
"email": "john@company.com",
"status": "valid",
"safe_to_send": true,
"confidence_score": 0.95,
"reason": "Verification completed",
"domain": "company.com",
"is_disposable": false,
"is_role_based": false,
"is_free": false,
"is_catch_all": false,
"mx_records": ["mx1.company.com"],
"smtp_response": null,
"verification_time_ms": 642,
"api_version": "1.0"
}
مثال على الاستجابة: نطاق catch-all
json
{
"email": "sarah@enterprise.io",
"status": "catchall",
"safe_to_send": false,
"confidence_score": 0.52,
"reason": "Catch-all domain detected",
"domain": "enterprise.io",
"is_disposable": false,
"is_role_based": false,
"is_free": false,
"is_catch_all": true,
"mx_records": ["mx1.enterprise.io"],
"smtp_response": null,
"verification_time_ms": 918,
"api_version": "1.0"
}
أمثلة برمجية
bash
curl -X POST https://verimails.com/api/verify/single \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com"}'
python
import requests
def verify_email(email, api_key):
response = requests.post(
"https://verimails.com/api/verify/single",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
},
json={"email": email}
)
response.raise_for_status()
return response.json()
result = verify_email("user@example.com", "YOUR_API_KEY")
if result["safe_to_send"]:
print("Safe to contact!")
javascript
async function verifyEmail(email, apiKey) {
const res = await fetch("https://verimails.com/api/verify/single", {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ email })
});
if (!res.ok) throw new Error(`API error: ${res.status}`);
return res.json();
}
const result = await verifyEmail("user@example.com", "YOUR_API_KEY");
console.log(result.status); // "valid"
console.log(result.safe_to_send); // true
php
function verifyEmail($email, $apiKey) {
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => "https://verimails.com/api/verify/single",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$apiKey}",
"Content-Type: application/json"
],
CURLOPT_POSTFIELDS => json_encode(["email" => $email])
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
return $result;
}
$result = verifyEmail("user@example.com", "YOUR_API_KEY");
if ($result["safe_to_send"]) {
echo "Safe to contact!";
}
رموز الحالة
| حالة HTTP | المعنى |
|---|---|
200 | نجاح: تم إرجاع النتيجة |
401 | غير مصرّح: مفتاح API مفقود أو غير صالح |
422 | خطأ في التحقق من صحة البيانات: صيغة بريد غير صالحة أو حقل مفقود |
429 | تم تجاوز حد المعدل: خفّفوا وتيرة الطلبات |
500 | خطأ في الخادم: حاولوا مجددًا بعد قليل |