الرئيسية › المستندات › مرجع API › النطاقات

النطاقات

أضف وأدر النطاقات المخصصة مع تتبُّع جاهزية الإرسال والاستقبال بشكل منفصل. تحقق من سجلات هوية المرسل وافحص توجيه MX بشكل مستقل.

نظرة عامة

افتراضياً، ترسل الصناديق من @agentsend.io. إضافة نطاقك تتيح الإرسال من عناوين مثل agent@yourdomain.com، مما يحسّن قابلية التسليم وثقة العلامة.

بعد إضافة نطاق، يُرجع AgentSend سجلات DNS منفصلة للإرسال والاستقبال. بمجرد نشرها، استدعِ نقطة التحقق لتحديث كلتا الحالتين: يفحص الإرسال التحقق من المرسل في SES وDKIM، بينما يفحص الاستقبال ما إذا كان MX للنطاق يشير إلى AgentSend.

ℹ

تتطلب جميع الطلبات ترويسة x-api-key. احصل على مفتاحك من لوحة التحكم.

كائن Domain

تُرجع جميع نقاط نهاية النطاقات كائن Domain (أو مصفوفة منها).

Domain object 
{
  "id":                 "dom_01hxyz...",          // UUID
  "domain":             "mail.yourdomain.com",
  "sendingStatus":      "pending",              // pending | pending_dkim | verified | failed
  "receivingStatus":    "pending",              // pending | verified | failed
  "verificationStatus": "pending",              // backward-compatible alias of sendingStatus
  "sendingDnsRecords": [
    {
      "type":  "TXT",
      "name":  "_amazonses.mail.yourdomain.com",
      "value": "verification-token"
    },
    {
      "type":  "CNAME",
      "name":  "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1.dkim.amazonses.com"
    }
  ],
  "receivingDnsRecords": [
    {
      "type":  "MX",
      "name":  "mail.yourdomain.com",
      "value": "mx.agentsend.io",
      "priority": 10
    }
  ],
  "dnsRecords": [
    {
      "type":  "TXT",
      "name":  "_amazonses.mail.yourdomain.com",
      "value": "verification-token"
    }
  ],
  "sendingVerifiedAt": null,
  "receivingVerifiedAt": null,
  "createdAt": "2024-11-01T09:00:00Z"
}
الحقل النوع الوصف
idstringالمعرّف الفريد للنطاق (UUID).
domainstringالنطاق أو النطاق الفرعي الذي أضفته.
sendingStatusstringحالة التحقق من المرسل. pending أو pending_dkim أو verified أو failed.
receivingStatusstringحالة توجيه الوارد استناداً إلى MX. pending أو verified أو failed.
verificationStatusstringاسم مستعار متوافق مع النسخ السابقة لـsendingStatus.
sendingDnsRecordsarrayسجلات DNS المطلوبة للتحقق من الإرسال وتوقيع DKIM.
receivingDnsRecordsarrayسجلات DNS المطلوبة إذا أردت أن يستقبل AgentSend البريد الوارد للنطاق.
dnsRecordsarrayقائمة مُدمَجة لسجلات الإرسال والاستقبال للراحة.
sendingVerifiedAtstring | nullوقت بلوغ التحقق من الإرسال الحالة verified آخر مرة.
receivingVerifiedAtstring | nullوقت بلوغ التحقق من MX الحالة verified آخر مرة.
createdAtstring (ISO 8601)طابع زمني لوقت إضافة النطاق.

POST /domains

أضف نطاقاً مخصصاً. تُرجع كائن Domain الجديد مع سجلات DNS التي يجب نشرها قبل التحقق.

جسم الطلب

المعاملTypeDescription
domain مطلوب string النطاق أو النطاق الفرعي المطلوب إضافته، مثل mail.yourdomain.com.
curl 
curl -X POST https://api.agentsend.io/domains \
  -H "x-api-key: $AGENTSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mail.yourdomain.com"}'

الاستجابة 201 Created

json 
{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "pending",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "mail.yourdomain.com",
      "value": "v=spf1 include:spf.agentsend.io ~all"
    },
    {
      "type": "CNAME",
      "name": "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1._domainkey.agentsend.io"
    },
    {
      "type": "CNAME",
      "name": "agsend2._domainkey.mail.yourdomain.com",
      "value": "agsend2._domainkey.agentsend.io"
    }
  ],
  "createdAt": "2024-11-01T09:00:00Z"
}
💡

انشر جميع dnsRecords المُرجَعة لدى مسجِّل DNS، ثم استدعِ POST /domains/{id}/verify لتفعيل النطاق.

GET /domains

اعرض جميع النطاقات في حسابك مع حالة التحقق الحالية لكل منها.

المعاملات

لا توجد معاملات استعلام.

curl 
curl https://api.agentsend.io/domains \
  -H "x-api-key: $AGENTSEND_API_KEY"

الاستجابة 200 OK

json 
{
  "data": [
    {
      "id": "dom_01hxyz4k9s2n3p7q",
      "domain": "mail.yourdomain.com",
      "verificationStatus": "verified",
      "dnsRecords": [ /* ... */ ],
      "createdAt": "2024-11-01T09:00:00Z"
    },
    {
      "id": "dom_01hzab8m3t4r2w9c",
      "domain": "outbound.acme.io",
      "verificationStatus": "pending",
      "dnsRecords": [ /* ... */ ],
      "createdAt": "2024-11-15T14:23:00Z"
    }
  ]
}

GET /domains/{id}

استرجع نطاقاً واحداً حسب المعرّف، بما في ذلك سجلات DNS الكاملة وحالة التحقق الحالية.

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

ParameterTypeDescription
id مطلوب string (uuid) معرّف النطاق المطلوب استرجاعه.
curl 
curl https://api.agentsend.io/domains/dom_01hxyz4k9s2n3p7q \
  -H "x-api-key: $AGENTSEND_API_KEY"

Response 200 OK

json 
{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "verified",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "mail.yourdomain.com",
      "value": "v=spf1 include:spf.agentsend.io ~all"
    },
    {
      "type": "CNAME",
      "name": "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1._domainkey.agentsend.io"
    },
    {
      "type": "CNAME",
      "name": "agsend2._domainkey.mail.yourdomain.com",
      "value": "agsend2._domainkey.agentsend.io"
    }
  ],
  "createdAt": "2024-11-01T09:00:00Z"
}

DELETE /domains/{id}

احذف نطاقاً من حسابك نهائياً. ستعود الصناديق التي تستخدم هذا النطاق إلى عناوين @agentsend.io. هذا الإجراء لا رجعة فيه.

Path parameters

ParameterTypeDescription
id مطلوب string (uuid) معرّف النطاق المطلوب حذفه.
curl 
curl -X DELETE https://api.agentsend.io/domains/dom_01hxyz4k9s2n3p7q \
  -H "x-api-key: $AGENTSEND_API_KEY"

الاستجابة 204 No Content

تُرجع جسماً فارغاً عند النجاح.

⚠

حذف النطاق لا يزيل سجلات DNS من المسجِّل. ينبغي عليك تنظيفها يدوياً بعد الحذف.

POST /domains/{id}/verify

أجرِ فحص جاهزية نطاق جديد. يحدّث AgentSend التحقق من المرسل من SES وDKIM، ثم يفحص بشكل منفصل ما إذا كان MX للنطاق يشير إلى AgentSend للبريد الوارد.

Path parameters

ParameterTypeDescription
id مطلوب string (uuid) معرّف النطاق المطلوب التحقق منه.
curl 
curl -X POST https://api.agentsend.io/domains/dom_01hxyz4k9s2n3p7q/verify \
  -H "x-api-key: $AGENTSEND_API_KEY"

Response 200 OK

تُرجع كائن Domain المحدَّث. تحقق من sendingStatus وreceivingStatus لرؤية آخر نتيجة.

json — verified 
{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "verified",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "mail.yourdomain.com",
      "value": "v=spf1 include:spf.agentsend.io ~all"
    },
    {
      "type": "CNAME",
      "name": "agsend1._domainkey.mail.yourdomain.com",
      "value": "agsend1._domainkey.agentsend.io"
    },
    {
      "type": "CNAME",
      "name": "agsend2._domainkey.mail.yourdomain.com",
      "value": "agsend2._domainkey.agentsend.io"
    }
  ],
  "createdAt": "2024-11-01T09:00:00Z"
}
json — pending_dkim (ownership ok, DKIM not yet propagated) 
{
  "id": "dom_01hxyz4k9s2n3p7q",
  "domain": "mail.yourdomain.com",
  "verificationStatus": "pending_dkim",
  "dnsRecords": [ /* ... */ ],
  "createdAt": "2024-11-01T09:00:00Z"
}
ℹ

قد يستغرق انتشار تغييرات DNS عالمياً حتى 48 ساعة. إذا أرجع التحقق pending_dkim أو failed، انتظر بضع دقائق واستدعِ التحقق مجدداً.

← السابق API: Webhooks