بهروزرسانی یک دامنه
دامنهٔ ردیابی سفارشی و دامنهٔ فایلهای سفارشیِ دامنه را تنظیم میکند، دوباره بررسی میکند یا برمیدارد؛ همان دو چیزی که این API میتواند دربارهٔ یک دامنه عوض کند.
فراخوانی واقعی را با کلید خودتان روی فضای کاری شما اجرا میکند.
PATCH /domains/{id}
دامنهٔ ردیابی سفارشی و دامنهٔ فایلهای سفارشیِ دامنه را تنظیم میکند، دوباره بررسی میکند یا برمیدارد؛ همان دو چیزی که این API میتواند دربارهٔ یک دامنه عوض کند.
درخواست
هر دامنه میتواند یک دامنهٔ ردیابی سفارشی و یک دامنهٔ فایلهای سفارشی داشته باشد، هرکدام زیردامنهای از خودش که شما انتخاب میکنید، مانند links.acme.com و files.acme.com، بهمحض اینکه تأیید شود یا رکورد TXT _openemail-challenge آن منتشر شود. لازم نیست هنوز نامه دریافت کند. تنظیم هرکدام نشانیای را تنها برای همان نام آماده میکند که در target گزارش میشود، و record همان رکورد CNAME است که آن نام را به آن نشانی میبرد. پس از آنکه بررسیای موفق شد، پیوندهای ردیابیشده و پیکسل بازشدن در نامههای تازهٔ آن دامنه بهجای میزبان پیشفرض از https://links.acme.com/t/... استفاده میکنند، و پیوندهای دانلود فایلهای ارسالی از آن از https://files.acme.com/f/....
پارامترها
trackingHoststring | null- زیردامنهای که برای پیوندهای ردیابیشده و پیکسل بازشدن به کار میرود، دستبالا ۵۱۲ نویسه. هرس و به حروف کوچک تبدیل میشود، و `https://` یا `http://` ابتدایی، مسیر و نقطهٔ پایانی پیش از بررسی حذف میشوند. مقدار تازه جایگزین دامنهٔ ردیابی کنونی میشود، مقدار کنونی بررسی را دوباره اجرا میکند، `null` یا رشتهٔ خالی آن را برمیدارد، و جاگذاشتن فیلد آن را دستنخورده رها میکند.
storageHoststring | null- زیردامنهای که برای پیوندهای دانلود فایل به کار میرود، به همان شکل تمیز میشود و به همان ۵۱۲ نویسه پایبند است. مقدار تازه جایگزین دامنهٔ فایلهای کنونی میشود، مقدار کنونی بررسی را دوباره اجرا میکند، `null` یا رشتهٔ خالی آن را برمیدارد، و جاگذاشتن فیلد آن را دستنخورده رها میکند.
بدنه دربارهٔ کلیدها سختگیر است و دربارهٔ تعدادشان آسانگیر. هر کلیدی جز trackingHost و storageHost یک 422 unknown_parameter است، و بدنهای که هیچکدام را نداشته باشد بیاثر است و با 200 و دامنه به همان شکلی که هست پاسخ میدهد. هر دو میتوانند در یک فراخوانی بیایند، و به ترتیب اعمال میشوند، اول trackingHost: یک trackingHost ردشده فراخوانی را پیش از آنکه storageHost لمس شود متوقف میکند، و یک storageHost ردشده تغییری را که از پیش روی trackingHost انجام شده سر جایش نگه میدارد. وقتی هرکدام باید مستقل بایستد، آنها را جدا بفرستید.
تنظیم یک دامنهٔ ردیابی و یک دامنهٔ فایلها
به domains:write نیاز دارد. هر میزبان در همان فراخوانی اعتبارسنجی، ذخیره و بررسی میشود، پس پاسخ از همان اول نتیجهٔ آن بررسی نخست را با خود دارد. بدنه همان بدنهٔ GET /domains/{id} است.
curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "trackingHost": "links.acme.com", "storageHost": "files.acme.com" }'{ "object": "domain", "id": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f", "domain": "acme.com", "receiving": { "verified": true, "verifiedAt": "2026-08-14T10:02:00.000Z", "catchAll": false, "lastCheckedAt": "2026-08-29T06:00:00.000Z", "error": null }, "sending": { "status": "verified", "canSend": true, "checkedAt": "2026-08-29T06:00:00.000Z", "error": null, "note": "Mail from this domain is signed and can be sent." }, "tracking": { "host": "links.acme.com", "status": "pending", "active": false, "target": "oelinks3f9a1c7e2b8d4a60.edge.openemail.uk", "record": { "type": "CNAME", "name": "links.acme.com", "value": "oelinks3f9a1c7e2b8d4a60.edge.openemail.uk" }, "checkedAt": "2026-08-29T06:05:12.000Z", "verifiedAt": null, "error": "links.acme.com does not resolve yet. Add a CNAME record named links.acme.com with the value oelinks3f9a1c7e2b8d4a60.edge.openemail.uk, then check again." }, "storage": { "host": "files.acme.com", "status": "pending", "active": false, "target": "oefiles81c40d6b2f7e9a35.edge.openemail.uk", "record": { "type": "CNAME", "name": "files.acme.com", "value": "oefiles81c40d6b2f7e9a35.edge.openemail.uk" }, "checkedAt": "2026-08-29T06:05:12.000Z", "verifiedAt": null, "error": "files.acme.com does not resolve yet. Add a CNAME record named files.acme.com with the value oefiles81c40d6b2f7e9a35.edge.openemail.uk, then check again." }, "addresses": [ { "address": "[email protected]", "enabled": true } ], "createdAt": "2026-08-14T09:55:11.000Z"}tracking.record و storage.record را نزد ارائهدهندهٔ DNS خود بهصورت CNAMEهای ساده منتشر کنید، با هر پراکسیای خاموش. بررسی هر نام را resolve میکند و سپس از https://links.acme.com/t/v/<nonce> یا https://files.acme.com/f/v/<nonce> پاسخی امضاشده به دست OpenEmail میخواهد. یک redirect بررسی را رد میکند، و یک پراکسی جلوی نام هم میتواند همین کار را بکند.
پس از آنکه رکورد resolve شد، یک بررسی میتواند گزارش دهد که نام به OpenEmail اشاره میکند و منتظر روشنشدن است. آن، صدور گواهی HTTPS آن است که در سمت ما رخ میدهد، از شما چیزی نمیخواهد و ممکن است کمی طول بکشد. پس از پایانش، نخستین بررسی موفق status را روی active میگذارد.
اگر نشانی در حین فراخوانی آماده نشده باشد، record برابر null است، target رشتهٔ خالی است و error میگوید که در حال آمادهشدن است. ظرف چند دقیقه و بدون فراخوانی دیگری تمام میشود، پس برای گرفتن رکورد دامنه را دوباره با GET /domains/{id} بخوانید.
این دو نام از هم مستقلاند. فراخوانیای که تنها یکی از فیلدها را دارد شیء دیگر را دقیقاً همانطور که بود رها میکند، پس راهاندازی بعدی فایلها هرگز مزاحم دامنهٔ ردیابیای که از پیش زنده است نمیشود.
دوباره بررسی کنید، یا برش دارید
برای اینکه بررسی همین حالا اجرا شود و منتظر بررسی زمانبندیشدهٔ بعدی نمانید، همان میزبانی را که دامنه از پیش دارد بفرستید. اگر آخرین بررسی، چه زمانبندیشده و چه نه، کمتر از ۳۰ ثانیه پیش اجرا شده باشد، فراخوانی وضعیت ذخیرهشده را بدون تغییر برمیگرداند. برای برداشتن یک نام در آن فیلد null بفرستید، و فیلد دیگر را جا بگذارید تا نامی که دارد حفظ شود.
curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "trackingHost": null }'{ "host": null, "status": "none", "active": false, "target": "", "record": null, "checkedAt": null, "verifiedAt": null, "error": null}پیوندهای درون نامههایی که پیشتر فرستاده شدهاند همان میزبانی را که با آن بیرون رفتهاند نگه میدارند، و این بهاندازهٔ یک پیوند ردیابیشده، پیوند دانلود روی یک فایل را هم در بر میگیرد. پس از آنکه نامی را بردارید یا عوض کنید، آن پیوندها تا وقتی رکورد CNAME قدیمی سر جایش بماند کار میکنند. راهاندازی دوبارهٔ یک نام ممکن است record متفاوتی به آن بدهد، پس همان رکوردی را منتشر کنید که پاسخ گزارش میدهد.
شیء tracking
hoststring | null- دامنهٔ ردیابی، یا null وقتی دامنه هیچکدام را ندارد.
status'none' | 'pending' | 'active' | 'failed'- `none` یعنی هیچ دامنهٔ ردیابیای تنظیم نشده. `pending` یعنی یکی تنظیم شده و هرگز بررسیای را با موفقیت نگذرانده. `active` یعنی نامههای تازه از آن استفاده میکنند. `failed` یعنی پیشتر بررسیای را گذرانده و از آن پس از کار افتاده است.
activeboolean- دقیقاً وقتی درست است که `status` برابر `active` باشد، یعنی وقتی پیوندهای ردیابیشده و پیکسل بازشدن در نامههای تازهٔ آن دامنه از این میزبان استفاده میکنند.
targetstring- نشانیای که رکورد CNAME به آن اشاره میکند، تنها برای همین دامنهٔ ردیابی آماده شده. تا وقتی `host` برابر null است، و تا وقتی نشانیِ یک میزبان تازه هنوز در حال آمادهشدن است، رشتهٔ خالی است.
record{ type: 'CNAME'; name: string; value: string } | null- رکوردی که باید منتشر شود، با نامِ `host` و مقدار `target`. وقتی دامنهٔ ردیابیای نیست null است، و همچنین تا وقتی نشانیِ یک میزبان تازه هنوز در حال آمادهشدن است.
checkedAtstring | null- آخرین باری که میزبان بررسی شده، ISO 8601. تا نخستین بررسی null است.
verifiedAtstring | null- آخرین باری که بررسیای موفق شده، ISO 8601. برای میزبانی که هرگز بررسیای را نگذرانده null است.
errorstring | null- آنچه آخرین بررسی یافته، با واژههایی که صاحب دامنه بتواند بر اساسشان کاری بکند. وقتی آخرین بررسی موفق بوده یا هنوز هیچ بررسیای اجرا نشده null است. میزبانی که یک یا دو بررسی را رد کرده باشد هنوز `active` است و دلیلش را اینجا با خود دارد.
شیء storage
دامنهٔ فایلها در storage گزارش میشود، فیلد به فیلد همان tracking. تنها چیزی که فرق میکند این است که نام برای چه به کار میرود: active آنجا یعنی پیوندهای دانلود فایلهای ارسالی از آن دامنه به آن اشاره میکنند.
hoststring | null- دامنهٔ فایلها، یا null وقتی دامنه هیچکدام را ندارد.
status'none' | 'pending' | 'active' | 'failed'- `none` یعنی هیچ دامنهٔ فایلهایی تنظیم نشده. `pending` یعنی یکی تنظیم شده و هرگز بررسیای را با موفقیت نگذرانده. `active` یعنی نامههای تازه از آن استفاده میکنند. `failed` یعنی پیشتر بررسیای را گذرانده و از آن پس از کار افتاده است.
activeboolean- دقیقاً وقتی درست است که `status` برابر `active` باشد، یعنی وقتی پیوندهای دانلود فایلهای ارسالی از آن دامنه از این میزبان استفاده میکنند.
targetstring- نشانیای که رکورد CNAME به آن اشاره میکند، تنها برای همین دامنهٔ فایلها آماده شده. تا وقتی `host` برابر null است، و تا وقتی نشانیِ یک میزبان تازه هنوز در حال آمادهشدن است، رشتهٔ خالی است.
record{ type: 'CNAME'; name: string; value: string } | null- رکوردی که باید منتشر شود، با نامِ `host` و مقدار `target`. وقتی دامنهٔ فایلهایی نیست null است، و همچنین تا وقتی نشانیِ یک میزبان تازه هنوز در حال آمادهشدن است.
checkedAtstring | null- آخرین باری که میزبان بررسی شده، ISO 8601. تا نخستین بررسی null است.
verifiedAtstring | null- آخرین باری که بررسیای موفق شده، ISO 8601. برای میزبانی که هرگز بررسیای را نگذرانده null است.
errorstring | null- آنچه آخرین بررسی یافته، با واژههایی که صاحب دامنه بتواند بر اساسشان کاری بکند. وقتی آخرین بررسی موفق بوده یا هنوز هیچ بررسیای اجرا نشده null است. میزبانی که یک یا دو بررسی را رد کرده باشد هنوز `active` است و دلیلش را اینجا با خود دارد.
میزبان چگونه بررسی میشود
هر دو نام با همان زمانبندی بررسی میشوند، و هرکدام جداگانه.
- میزبانی که هنوز بررسیای را نگذرانده، در ساعت نخست هر ۲ دقیقه، در روز نخست هر ۱۰ دقیقه، در هفتهٔ نخست ساعتی یک بار و پس از آن هر ۶ ساعت بررسی میشود.
- میزبان فعال هر ۱۰ دقیقه بررسی میشود، و بررسی ناموفق روی آن پس از ۱ دقیقه و سپس پس از ۲ دقیقه دوباره تلاش میشود.
- میزبان فعال پس از سه بررسی ناموفق پشتسرهم، یا وقتی بیش از ۲ ساعت از آخرین بررسی موفقش گذشته باشد، دیگر به کار نمیرود. نامههای تازه آنگاه به میزبان پیشفرض برمیگردند، و
statusتا وقتی بررسیای دوباره موفق شودfailedخوانده میشود. بررسیها ادامه مییابند، هر بار با فاصلهٔ بیشتر و دستبالا با یک ساعت فاصله.
دامنهٔ ردیابی تنها به مسیرهای ردیابی پاسخ میدهد و دامنهٔ فایلها تنها به مسیرهای دانلود، و هرکدام تنها برای نامههایی که فضای کاریِ صاحبش فرستاده پاسخ میدهند.
خطاها
| وضعیت | type | code | چه زمانی |
|---|---|---|---|
| 400 | invalid_request_error | malformed_json | بدنه JSON معتبر نیست. |
| 403 | permission_error | insufficient_scope | کلید domains:write را ندارد. |
| 404 | not_found_error | resource_not_found | دامنهای با آن شناسه در این فضای کاری نیست. |
| 409 | conflict_error | domain_not_verified | میزبان تازهای فرستاده شده در حالی که receiving.verified نادرست است و رکورد TXT _openemail-challenge دامنه هنوز منتشر نشده. param همان فیلدی است که مقدار روی آن آمده، trackingHost یا storageHost. |
| 409 | conflict_error | tracking_host_in_use | دامنهٔ دیگری از پیش این میزبان را بهعنوان دامنهٔ ردیابی خود به کار میبرد، یا میزبان از پیش بهعنوان دامنهٔ فایلها در استفاده است، یا دامنهٔ ردیابی این دامنه را یک سرور OpenEmail دیگر مدیریت میکند. param برابر trackingHost است. |
| 409 | conflict_error | storage_host_in_use | همان سه حالت برای دامنهٔ فایلها: دامنهٔ دیگری از پیش این میزبان را بهعنوان دامنهٔ فایلهای خود به کار میبرد، یا میزبان از پیش بهعنوان دامنهٔ ردیابی در استفاده است، یا دامنهٔ فایلها اینجا را یک سرور OpenEmail دیگر مدیریت میکند. param برابر storageHost است. |
| 422 | validation_error | invalid_tracking_host | میزبان یک hostname معتبر نیست، یا مجاز نیست: باید زیردامنهای اکید از خود دامنه باشد، و نمیتواند میزبان مسیر بازگشت bounce.<domain>، نامی متعلق به OpenEmail یا دامنهای باشد که برای دریافت نامه راهاندازی شده. param برابر trackingHost است. |
| 422 | validation_error | invalid_storage_host | همان قواعد، ردشده روی دامنهٔ فایلها. param برابر storageHost است. |
| 422 | validation_error | unknown_parameter | کلیدی در بدنه جز trackingHost و storageHost. |
| 422 | validation_error | invalid_parameter | بدنه یک شیء JSON نیست، یا فیلدی که حاضر است نه string است و نه null، یا از ۵۱۲ نویسه میگذرد. بدنهای که هیچیک از دو فیلد را ندارد خطا نیست: چیزی را عوض نمیکند و با 200 برمیگردد. |
| 422 | validation_error | capability_unsupported | کلید به نشانیهای تکی محدود شده، نه به کل این دامنه، در حالی که هر دو نام به همهٔ نشانیهای روی دامنه مربوطاند. کلیدی که دامنه را در domainAllowlist دارد میتواند آنها را تنظیم کند. param برابر domainAllowlist است. |