إعداد DNS لنطاق
ما إذا كان OpenEmail يكتب سجلات النطاق بنفسه، وعبر أي منطقة مرتبطة، وما وضع كل نوع من السجلات.
ينفّذ أيًّا من الاستدعاءات الـ3 على مساحة عملك.
GET /domains/{id}/dns
ما إذا كان OpenEmail يكتب سجلات النطاق بنفسه، وعبر أي منطقة مرتبطة، وما وضع كل نوع من السجلات.
قراءة الإعداد
يتطلب domains:read. وmanaging يساوي true ما دام OpenEmail يكتب السجلات بنفسه. ويبيّن zone أي منطقة مرتبطة تستجيب للنطاق: resolved حين تستجيب منطقة واحدة، وambiguous حين تستجيب عدة مناطق ويلزم الاختيار بينها، وnone حين لا تضمّه أي منطقة، أو unusable حين يتعذّر سؤال الاتصالات. أضف ?refresh=true لسؤال المزوّدين من جديد.
curl "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/dns" -H "$AUTH"{ "object": "domain_dns", "domainId": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "domain": "acme.com", "managing": true, "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "connection": { "id": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "status": "active", "subject": "[email protected]", "accounts": [{ "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }] }, "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", "zoneName": "acme.com", "zoneHolder": "Acme", "state": "ready", "steps": [ { "purpose": "mx", "ok": true, "detail": "MX records are in place.", "visibility": "public", "records": [] } ], "leftovers": [], "probe": null, "error": null, "syncedAt": "2026-09-30T08:01:12.000Z", "zone": { "kind": "resolved", "checkedAt": "2026-10-01T09:00:00.000Z", "cached": true, "candidate": { "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "subject": "[email protected]", "status": "active", "accounts": [{ "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }], "account": { "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }, "zone": { "id": "023e105f4ecef8ad9ca31a8372d0c353", "name": "acme.com", "accountId": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "active": true, "status": "active", "type": "full", "nameServers": ["ana.ns.cloudflare.com", "bob.ns.cloudflare.com"], "covers": true } }, "candidates": [], "reason": null, "connected": null, "host": null, "blocked": [] }}تسرد leftovers السجلات التي كتبها OpenEmail وتعذّرت عليه إزالتها، لتحذفها يدويًا لدى المزوّد.
اختيار المنطقة
يتطلب domains:write. يربط PUT /domains/{id}/dns مع { connectionId, zoneId } النطاقَ بمنطقة حين يمكن لعدة مناطق أن تستجيب له. ويجب أن تغطي المنطقة النطاق، وأن تكون نشطة، وأن تقبل سجلًا اختباريًا. ولا يُكتب شيء بعد.
curl -X PUT "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/dns" -H "$AUTH" \ -H "Content-Type: application/json" \ -d '{ "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "zoneId": "023e105f4ecef8ad9ca31a8372d0c353" }'{ "object": "domain_dns", "domainId": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "domain": "acme.com", "managing": true, "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "connection": { "id": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "status": "active", "subject": "[email protected]", "accounts": [{ "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }] }, "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", "zoneName": "acme.com", "zoneHolder": "Acme", "state": "awaiting-sync", "steps": [ { "purpose": "mx", "ok": true, "detail": "MX records are in place.", "visibility": "public", "records": [] } ], "leftovers": [], "probe": null, "error": null, "syncedAt": "2026-09-30T08:01:12.000Z", "zone": { "kind": "resolved", "checkedAt": "2026-10-01T09:00:00.000Z", "cached": true, "candidate": { "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "subject": "[email protected]", "status": "active", "accounts": [{ "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }], "account": { "id": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "name": "Acme" }, "zone": { "id": "023e105f4ecef8ad9ca31a8372d0c353", "name": "acme.com", "accountId": "4f1c2b3a5d6e7f8091a2b3c4d5e6f708", "active": true, "status": "active", "type": "full", "nameServers": ["ana.ns.cloudflare.com", "bob.ns.cloudflare.com"], "covers": true } }, "candidates": [], "reason": null, "connected": null, "host": null, "blocked": [] }}المنطقة التي لا تغطي النطاق تعطي 422 invalid_parameter على zoneId. والنطاق المُعدّ عبر منطقة أخرى يعطي 409 dns_zone_conflict، والمنطقة غير النشطة أو التي ترفض السجل الاختباري تعطي 409 dns_zone_unusable.
يحتاج رمز وصول OAuth إلى رمز تحقق لهذا الاستدعاء. وإلى أن يتحقق التطبيق من رمز خلال آخر 60 دقيقة، يردّ الاستدعاء بـ 403 step_up_required ولا يغيّر شيئًا. ولا يُطلب ذلك من مفتاح API أبدًا. وتبيّن صفحة المصادقة كيف تطلب رمزًا وتتحقق منه.
كتابة السجلات
يتطلب domains:write. يكتب POST /domains/{id}/dns/sync كل سجل يحتاجه النطاق أو يصلحه، كما تفعل المزامنة في التطبيق، ويربط المنطقة أولًا حين لا تستجيب إلا منطقة واحدة. أرسل { "purpose": "dmarc" } لكتابة نوع واحد فقط من السجلات.
curl -X POST "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/dns/sync" -H "$AUTH"{ "object": "domain_dns_sync", "outcome": "synced", "message": null, "attached": false, "provision": { "outcome": "applied", "state": "ready", "connectionId": "dnsl_3f9a1c2e7b4d4e6f8a0b2c3d", "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", "proven": true, "ownership": "The ownership record is in place.", "written": [{ "purpose": "dmarc", "name": "_dmarc.acme.com", "type": "TXT", "mode": "created" }], "adopted": 6, "conflicts": [], "failures": [], "steps": [], "retired": [], "leftovers": [], "probe": null, "error": null }, "dns": { "object": "domain_dns", "domain": "acme.com", "managing": true, "state": "ready", "…": "…" }, "zone": { "kind": "resolved", "cached": false, "…": "…" }}حين لا تستجيب منطقة واحدة بعينها، لا يُكتب شيء: يكون outcome هو refused، ويبيّن message السبب، ويسرد zone المناطق التي يُختار منها.
المزامنة الجارية بالفعل على النطاق تعطي 409 dns_busy، والمزوّد الذي يرفض الطلب يعطي 502 dns_provider_error. والنطاق الذي ينتظر سجلاته يُوثَّق بمجرد أن تصبح في مكانها.
يحتاج رمز وصول OAuth إلى رمز تحقق لهذا الاستدعاء. وإلى أن يتحقق التطبيق من رمز خلال آخر 60 دقيقة، يردّ الاستدعاء بـ 403 step_up_required ولا يغيّر شيئًا. ولا يُطلب ذلك من مفتاح API أبدًا. وتبيّن صفحة المصادقة كيف تطلب رمزًا وتتحقق منه.