إضافة نطاق

قبل إرسال البريد الإلكتروني عبر MailLand، يجب عليك إضافة نطاق إرسال واحد على الأقل والتحقق منه. يُثبت ذلك ملكيتك للنطاق ويُخوّل MailLand للإرسال نيابةً عنك.

إضافة نطاق

POST https://api.mail.land/v1/domains

Add a domain

curl -X POST https://api.mail.land/v1/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "yourdomain.com"
  }'

الاستجابة

الحالة: 201 Created

Domain response

{
  "id": "k3v9x2m8q1w7z4",
  "domain": "yourdomain.com",
  "verificationStatus": "pending",
  "spfStatus": "pending",
  "dkimStatus": "pending",
  "dmarcStatus": "pending",
  "isFullyVerified": false,
  "trackingSubdomain": "track",
  "useCustomTracking": false,
  "bounceSubdomain": "bounce",
  "useCustomBounce": true,
  "inboundEnabled": false,
  "inboundSubdomain": null,
  "mxVerified": false,
  "healthStatus": "unknown",
  "createdAt": "2026-02-17T10:00:00Z",
  "updatedAt": "2026-02-17T10:00:00Z"
}

الحقل	النوع	الوصف
`id`	string	معرّف النطاق العام
`domain`	string	اسم النطاق
`verificationStatus`	enum	`pending` أو `verified` أو `failed`
`spfStatus` / `dkimStatus` / `dmarcStatus`	enum	`pending` أو `valid` أو `invalid` لكل سجل
`isFullyVerified`	boolean	تم التحقق من الملكية وأن SPF وDKIM وDMARC جميعها `valid`، مطلوب للإرسال
`trackingSubdomain` / `bounceSubdomain`	string	النطاقات الفرعية للتتبع/الارتداد، سواء كان النطاق المخصص مفعّلاً أم لا
`useCustomTracking` / `useCustomBounce`	boolean	هل نطاق التتبع/الارتداد المخصص مفعّل
`inboundEnabled`	boolean	هل استقبال البريد الوارد مفعّل لهذا النطاق
`inboundSubdomain`	string \| null	النطاق الفرعي لسجل MX الوارد؛ `null` تعني جذر النطاق
`mxVerified`	boolean	هل سجل MX الوارد تم التحقق منه
`healthStatus`	enum	`unknown` أو `healthy` أو `warning` أو `critical`
`createdAt`	datetime	وقت إضافة النطاق

لا يوجد رمز تحقق: إضافة نطاق تُنشئ السجل وتولّد مفتاح DKIM الخاص به تلقائياً (بدون خطوة رمز).

بعد إضافة النطاق، يجب تهيئة سجلات DNS والتحقق من الملكية قبل أن تتمكن من إرسال البريد الإلكتروني. راجع إعداد DNS للاطلاع على السجلات المطلوبة.

مسار الإعداد

إضافة النطاق

استدعِ POST /v1/domains مع اسم نطاقك. تقوم MailLand بإنشاء سجل النطاق وتوليد مفتاح DKIM الخاص به.

الحصول على تعليمات DNS

استدعِ GET /v1/domains/{id}/dns-instructions لاسترداد سجلات DNS الدقيقة التي تحتاج إلى إنشائها. راجع إعداد DNS.

تهيئة سجلات DNS

أضف سجلات SPF وDKIM وDMARC (بالإضافة إلى نطاقَي CNAME الاختياريَّين للارتداد/التتبع إن كانا مفعّلين) إلى موفر DNS الخاص بك.

التحقق من النطاق

استدعِ POST /v1/domains/{id}/verify لتشغيل التحقق. تتحقق MailLand من جميع سجلات DNS وتحدّث حالة النطاق. راجع التحقق.

قائمة النطاقات

GET https://api.mail.land/v1/domains

List domains

curl https://api.mail.land/v1/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

List response

{
  "items": [
    {
      "id": "k3v9x2m8q1w7z4",
      "domain": "yourdomain.com",
      "verificationStatus": "verified",
      "spfStatus": "valid",
      "dkimStatus": "valid",
      "dmarcStatus": "valid",
      "isFullyVerified": true,
      "trackingSubdomain": "track",
      "useCustomTracking": false,
      "bounceSubdomain": "bounce",
      "useCustomBounce": false,
      "inboundEnabled": false,
      "inboundSubdomain": null,
      "mxVerified": false,
      "healthStatus": "healthy",
      "createdAt": "2026-02-17T10:00:00Z",
      "updatedAt": "2026-02-17T10:15:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

الحصول على نطاق

GET https://api.mail.land/v1/domains/{id}

يُرجع التفاصيل الكاملة للنطاق بما في ذلك حالة التحقق وجميع النطاقات الفرعية.

Get a domain

curl https://api.mail.land/v1/domains/k3v9x2m8q1w7z4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

تخصيص النطاقات الفرعية للتتبع والارتداد، وتبديل حالة الوارد. حقول الإعدادات الأخرى: useCustomTracking، useCustomBounce، inboundEnabled، inboundSubdomain. هذه التسميات لا تُفعَّل إلا بعد تفعيل العلَم المخصص المقابل والتحقق من السجل. تفعيل useCustomBounce يمسح التحقق من سجل الارتداد، لذا يجب التحقق من CNAME الخاص به مجددًا:

PATCH https://api.mail.land/v1/domains/{id}/settings

Update domain settings

curl -X PATCH https://api.mail.land/v1/domains/k3v9x2m8q1w7z4/settings \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "trackingSubdomain": "links",
    "bounceSubdomain": "returns"
  }'

يستلزم تغيير النطاقات الفرعية تحديث سجلات DNS وإعادة التحقق من النطاق.

حذف نطاق

DELETE https://api.mail.land/v1/domains/{id}

يُرجع 204 No Content عند النجاح. يؤدي حذف النطاق إلى:

إلغاء جميع مفاتيح DKIM المرتبطة بالنطاق
إيقاف جميع عمليات إرسال البريد الإلكتروني من هذا النطاق
إزالة توجيه التتبع والارتداد

Delete a domain

curl -X DELETE https://api.mail.land/v1/domains/k3v9x2m8q1w7z4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

الحذف دائم. لن تتمكن أي بيانات اعتماد API مقيّدة بهذا النطاق من إرسال البريد الإلكتروني. ستفشل الحملات أو الأتمتة النشطة التي تستخدم هذا النطاق.

استجابات الخطأ

الحالة	الكود	الوصف
`400`	`VALIDATION_FAILED`	تنسيق اسم النطاق غير صالح
`400`	`INVALID_REQUEST`	النطاق مُضاف بالفعل (لهذه المساحة أو لأخرى)
`400`	`DOMAIN_SUBDOMAIN_EMPTY`	إعدادات PATCH: تم إرسال حقل نطاق فرعي فارغًا
`400`	`DOMAIN_SUBDOMAIN_CONFLICT`	إعدادات PATCH: النطاق الفرعي المطلوب مستخدم بالفعل من سجل آخر لهذا النطاق
`404`	`DOMAIN_NOT_FOUND`	معرّف النطاق غير موجود
`403`	`PLAN_LIMIT_REACHED`	تم الوصول إلى الحد الأقصى من النطاقات لخطتك

تحدد MailLand عدد نطاقات الإرسال حسب الخطة، ويختلف الحد من خطة إلى أخرى (بعض الخطط غير محدودة). عند بلوغه تعيد إضافة نطاق 403 PLAN_LIMIT_REACHED. اطلع على خطتك الحالية في الفوترة.

الخطوات التالية

إعداد DNS: تهيئة سجلات SPF و DKIM و DMARC
التحقق: التحقق من ملكية النطاق
تدوير مفتاح DKIM: إدارة مفاتيح توقيع DKIM

إضافة نطاق