راه‌اندازی DNS یک دامنه
اینکه OpenEmail رکوردهای یک دامنه را خودش می‌نویسد یا نه، از طریق کدام زون متصل، و هر نوع رکورد در چه وضعی است.
هر کدام از 3 فراخوانی را روی فضای کاری شما اجرا می‌کند.
GET /domains/{id}/dns
اینکه OpenEmail رکوردهای یک دامنه را خودش می‌نویسد یا نه، از طریق کدام زون متصل، و هر نوع رکورد در چه وضعی است.
خواندن راه‌اندازی
به domains:read نیاز دارد. تا وقتی OpenEmail خودش رکوردها را می‌نویسد، managing برابر true است. 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 هرگز خواسته نمی‌شود. صفحهٔ احراز هویت نشان می‌دهد چطور کد بخواهید و آن را تأیید کنید.