الرئيسية › المستندات › النطاقات المخصصة

النطاقات المخصصة

أرسل البريد من علامتك التجارية وتتبع جاهزية الوارد منفصلة. أضف نطاقاً لإنشاء صناديق بريد بعناوين مثل agent@yourdomain.com بدلاً من @agentsend.io الافتراضي.

نظرة عامة

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

بمجرد التحقق من نطاق، يمكنك إنشاء صناديق بريد عليه وإرسال رسائل تبدو كأنها قادمة من عناوين مثل support@yourdomain.com أو assistant@yourdomain.com. يرى المستلمون نطاقك في ترويسة From. ستتبع الردود الواردة مسار MX الذي يستخدمه نطاقك، لذا وجّه MX إلى AgentSend فقط إذا أردت تسليم البريد الوارد إلى AgentSend.

ℹ

تتطلب النطاقات المخصصة إضافة سجلات DNS إلى مسجِّل نطاقك (Cloudflare أو Route 53 أو Namecheap، إلخ). تتحقق عملية التحقق من انتشار هذه السجلات قبل السماح بالإرسال.

إضافة نطاق

سجّل نطاقاً في AgentSend بإرسال طلب POST إلى /domains. تتضمن الاستجابة سجلات DNS التي يلزم إضافتها.

javascript 
const res = await fetch("https://api.agentsend.io/domains", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    domain: "yourdomain.com",
  }),
});

const domain = await res.json();
console.log(domain.id);               // "dom_..."
console.log(domain.sendingStatus);   // "pending"
console.log(domain.receivingStatus); // "pending"
console.log(domain.dnsRecords);      // combined DNS records to add

مثال على الاستجابة

json 
{
  "id": "dom_01hx4r2kt9fzv8s3n",
  "domain": "yourdomain.com",
  "sendingStatus": "pending",
  "receivingStatus": "pending",
  "verificationStatus": "pending",
  "createdAt": "2025-04-16T10:00:00.000Z",
  "dnsRecords": [
    {
      "type": "TXT",
      "host": "_amazonses.yourdomain.com",
      "value": "verification-token"
    },
    {
      "type": "CNAME",
      "host": "dkim-a._domainkey.yourdomain.com",
      "value": "dkim-a.dkim.amazonses.com"
    },
    {
      "type": "MX",
      "host": "yourdomain.com",
      "value": "mx.agentsend.io",
      "priority": 10
    }
  ]
}

إعداد DNS

بعد إضافة النطاق، انتقل إلى مزوّد DNS وأضف السجلات المُرجَعة في dnsRecords. تتحقق سجلات TXT وCNAME من هوية المرسل وتوقيع DKIM. سجل MX مطلوب فقط إذا أردت أيضاً أن يستقبل AgentSend البريد الوارد للنطاق.

النوع المضيف القيمة الغرض
MX yourdomain.com mx.agentsend.io (priority 10) يوجّه البريد الوارد لنطاقك إلى خوادم بريد AgentSend، بحيث تصل الردود إلى صندوق وكيلك.
TXT (verification) _amazonses.yourdomain.com SES verification token يؤكد أنك تتحكم في نطاق الإرسال في Amazon SES.
CNAME (DKIM) <token>._domainkey.yourdomain.com <token>.dkim.amazonses.com يوقّع الرسائل الصادرة تشفيرياً ليتمكن المستلمون من التحقق من أن AgentSend أرسلها بإذن من نطاقك.
💡

تنتشر تغييرات DNS عادة خلال بضع دقائق، وقد تستغرق حتى 48 ساعة في حالات نادرة. يمكنك تنفيذ dig TXT agentsend._domainkey.yourdomain.com من الطرفية للتحقق من أن سجل DKIM نشط.

⚠

إذا كان لنطاقك سجل MX مسبقاً، فإن إضافة سجل MX الخاص بـ AgentSend سيوجّه كل البريد الوارد لذلك النطاق إلى AgentSend. استخدم نطاقاً فرعياً (مثل mail.yourdomain.com) إذا احتجت للحفاظ على توجيه البريد القائم.

التحقق

بمجرد إضافة سجلات DNS، ابدأ التحقق باستدعاء POST /domains/{id}/verify. يحدّث AgentSend التحقق من المرسل ويفحص بشكل منفصل ما إذا كان MX يشير إلى AgentSend للبريد الوارد.

javascript 
const res = await fetch(
  `https://api.agentsend.io/domains/${domain.id}/verify`,
  {
    method: "POST",
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

const result = await res.json();
console.log(result.sendingStatus);   // "verified" | "pending_dkim" | "failed"
console.log(result.receivingStatus); // "verified" | "pending" | "failed"

تدفق الحالة

يُتتبّع sendingStatus وreceivingStatus بشكل منفصل. يبقى verificationStatus اسماً مستعاراً متوافقاً مع النسخ السابقة لـsendingStatus.

الحالة المعنى
pending تم تسجيل النطاق لكن لم تُجرَ محاولة تحقق بعد. لم تُفحَص أي سجلات DNS.
pending_dkim تم التحقق من ملكية النطاق، لكن سجلات DKIM لم تظهر بعد. انتظر بضع دقائق وأعد المحاولة.
verified تم تأكيد جميع سجلات DNS المطلوبة. النطاق جاهز لاستخدامه في إرسال البريد. لا يزال الاستقبال يعتمد على ما تشير إليه سجلات MX للنطاق.
failed فشل التحقق. تعذّر العثور على واحد أو أكثر من السجلات المطلوبة. تحقق من صحة إدخال السجلات لدى مزوّد DNS وأعد المحاولة.
ℹ

يمكنك استدعاء /domains/{id}/verify أي عدد من المرات. الاستعلام الدوري آمن — مثلاً، استدعِه كل 30 ثانية حتى تصبح الحالة verified.

خصائص النطاق

يحتوي كائن النطاق على الحقول التالية:

الخاصية Type Description
id string المعرّف الفريد للنطاق، مع بادئة dom_.
domain string اسم النطاق كما قُدّم عند إنشائه، مثل yourdomain.com.
sendingStatus string حالة التحقق من المرسل الحالية: pending أو pending_dkim أو verified أو failed.
receivingStatus string حالة توجيه الوارد الحالية استناداً إلى MX: pending أو verified أو failed.
verificationStatus string اسم مستعار متوافق مع النسخ السابقة لـsendingStatus.
dnsRecords array مصفوفة كائنات سجلات DNS يجب إضافتها إلى مزوّد DNS. لكل سجل type وhost وvalue وقد يحتوي priority.
createdAt string (ISO 8601) طابع زمني لوقت تسجيل النطاق في AgentSend.

إنشاء صناديق بريد على نطاقات مخصصة

بمجرد أن يصبح النطاق verified، مرّر id الخاص به كـdomainId عند إنشاء صندوق. سيستخدم عنوان الصندوق نطاقك بدلاً من @agentsend.io.

javascript 
const res = await fetch("https://api.agentsend.io/inboxes", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    displayName: "Support Agent",
    username: "support",       // becomes support@yourdomain.com
    domainId: "dom_01hx4r2kt9fzv8s3n",
  }),
});

const inbox = await res.json();
console.log(inbox.address); // "support@yourdomain.com"
💡

يحدد حقل username الجزء المحلي من عنوان البريد. إذا تركته، ينشئ AgentSend واحداً عشوائياً. يمكنك إنشاء أي عدد من الصناديق على نفس النطاق الذي تم التحقق منه.

حذف نطاق

أزل نطاقاً بطلب DELETE إلى /domains/{id}.

javascript 
await fetch(`https://api.agentsend.io/domains/${domain.id}`, {
  method: "DELETE",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});
⚠

حذف النطاق نهائي. ستفقد جميع الصناديق المرتبطة بالنطاق عناوينها ولن تتمكن من إرسال أو استقبال البريد. تُحفَظ الرسائل القائمة في تلك الصناديق، لكن لا يمكن تسليم بريد جديد. لا يمكن التراجع عن هذا الإجراء.

← السابق Webhooks