Alan adı güncelleme
Alan adının özel izleme alan adını ve özel dosya alan adını ayarlar, yeniden denetler veya kaldırır; bu API'nin bir alan adında değiştirebildiği iki şey bunlardır.
Gerçek çağrıyı kendi anahtarınızla çalışma alanınıza karşı çalıştırır.
PATCH /domains/{id}
Alan adının özel izleme alan adını ve özel dosya alan adını ayarlar, yeniden denetler veya kaldırır; bu API'nin bir alan adında değiştirebildiği iki şey bunlardır.
İstek
Bir alan adı, kendisinin alt alan adı olarak seçtiğiniz birer özel izleme alan adına ve özel dosya alan adına sahip olabilir (örneğin links.acme.com ve files.acme.com); bunun için alan adının doğrulanmış olması ya da _openemail-challenge TXT kaydının yayımlanmış olması yeterlidir. Henüz posta alıyor olması gerekmez. Birini ayarlamak yalnızca o ad için bir adres hazırlar, bu adres target alanında bildirilir ve record, adı o adrese yönlendiren CNAME kaydıdır. Bir denetim geçtikten sonra, alan adından gönderilen yeni postalardaki izlenen bağlantılar ve açılma pikseli varsayılan sunucu yerine https://links.acme.com/t/... adresini, ondan gönderilen dosyaların indirme bağlantıları ise https://files.acme.com/f/... adresini kullanır.
Parametreler
trackingHoststring | null- İzlenen bağlantılar ve açılma pikseli için kullanılacak alt alan adı; en çok 512 karakter. Kırpılır, küçük harfe çevrilir ve denetlenmeden önce baştaki `https://` ya da `http://`, yol ve sondaki nokta ayıklanır. Yeni bir değer mevcut izleme alan adının yerini alır, mevcut değerin gönderilmesi denetimi yeniden çalıştırır, `null` veya boş dize onu kaldırır, alanı hiç göndermemek ise olduğu gibi bırakır.
storageHoststring | null- Dosya indirme bağlantıları için kullanılacak alt alan adı; aynı şekilde temizlenir ve aynı 512 karakter sınırına tabidir. Yeni bir değer mevcut dosya alan adının yerini alır, mevcut değerin gönderilmesi denetimi yeniden çalıştırır, `null` veya boş dize onu kaldırır, alanı hiç göndermemek ise olduğu gibi bırakır.
Gövde, anahtarlar konusunda katı, kaç tane gönderdiğiniz konusunda esnektir. trackingHost ve storageHost dışındaki her anahtar 422 unknown_parameter verir; ikisini de taşımayan bir gövde hiçbir şey yapmaz ve alan adını olduğu gibi 200 ile döndürür. İkisi tek bir çağrıda gönderilebilir ve sırayla, önce trackingHost olmak üzere uygulanır: reddedilen bir trackingHost çağrıyı storageHost işlenmeden durdurur, reddedilen bir storageHost ise o sırada yapılmış bir trackingHost değişikliğini yerinde bırakır. Her biri kendi başına durmak zorundaysa ayrı ayrı gönderin.
İzleme alan adı ve dosya alan adı ayarlama
domains:write gerektirir. Her host aynı çağrı içinde doğrulanır, kaydedilir ve denetlenir; bu yüzden yanıt ilk denetimin sonucunu da taşır. Gövde GET /domains/{id} ile aynıdır.
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 ve storage.record kayıtlarını DNS sağlayıcınızda düz CNAME olarak, proxy kapalı biçimde yayımlayın. Denetim her adı çözümler, ardından https://links.acme.com/t/v/<nonce> ya da https://files.acme.com/f/v/<nonce> adresinden OpenEmail tarafından imzalanmış bir yanıt ister. Bir yönlendirme denetimi başarısız kılar; adın önündeki bir proxy de aynı sonucu verebilir.
Kayıt çözümlendikten sonra bir denetim, adın OpenEmail'i gösterdiğini ve açılmayı beklediğini bildirebilir. Bu, bizim tarafımızda gerçekleşen, sizden bir şey istemeyen ve biraz zaman alabilen HTTPS sertifikası verme sürecidir. O tamamlandığında, geçen ilk denetim status değerini active yapar.
Adres çağrı sırasında hazırlanamadıysa record null, target boş bir dize olur ve error adresin hazırlanmakta olduğunu söyler. Bu işlem başka bir çağrı gerekmeden birkaç dakika içinde biter; kayıt için alan adını GET /domains/{id} ile yeniden okuyun.
İki ad birbirinden bağımsızdır. Tek bir alan taşıyan bir çağrı diğer nesneyi olduğu gibi bırakır; bu yüzden dosya alan adını sonradan kurmak, hâlihazırda çalışan bir izleme alan adını asla bozmaz.
Yeniden denetleme veya kaldırma
Denetimi bir sonraki planlanmış denetimi beklemeden şimdi çalıştırmak için alan adının hâlihazırda sahip olduğu host'u gönderin. Son denetim, planlı olsun olmasın, 30 saniyeden kısa süre önce çalıştıysa çağrı saklanan durumu değiştirmeden döndürür. Bir adı kaldırmak için o alana null gönderin; tuttuğu adı korumak için diğer alanı hiç göndermeyin.
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}Hâlihazırda gönderilmiş postalardaki bağlantılar çıktıkları host'u korur; bu, bir dosyanın indirme bağlantısı için de izlenen bir bağlantı kadar geçerlidir. Bir adı kaldırdıktan ya da değiştirdikten sonra, eski CNAME kaydı yerinde kaldığı sürece bu bağlantılar çalışmayı sürdürür. Bir adı yeniden kurmak ona farklı bir record verebilir; bu yüzden yanıtın bildirdiği kaydı yayımlayın.
tracking nesnesi
hoststring | null- İzleme alan adı; alan adının izleme alan adı yoksa null.
status'none' | 'pending' | 'active' | 'failed'- `none`, hiçbir izleme alan adının ayarlanmadığı anlamına gelir. `pending`, biri ayarlanmış ama hiç denetim geçmemiş demektir. `active`, yeni postaların onu kullandığı anlamına gelir. `failed`, daha önce bir denetim geçtiğini ve o zamandan beri kullanımdan çıktığını gösterir.
activeboolean- Tam olarak `status` `active` iken true olur; yani alan adından gönderilen yeni postalardaki izlenen bağlantılar ve açılma pikseli host'u kullandığında.
targetstring- CNAME kaydının işaret ettiği, yalnızca bu izleme alan adı için hazırlanmış adres. `host` null olduğu sürece ve yeni bir host'un adresi hâlâ hazırlanırken boş bir dizedir.
record{ type: 'CNAME'; name: string; value: string } | null- Yayımlanacak kayıt: adı `host`, değeri `target` olur. İzleme alan adı yokken ve yeni bir host'un adresi hâlâ hazırlanırken null olur.
checkedAtstring | null- Host'un en son ne zaman denetlendiği, ISO-8601. İlk denetime kadar null.
verifiedAtstring | null- Bir denetimin en son ne zaman geçtiği, ISO-8601. Hiç denetim geçmemiş bir host için null.
errorstring | null- Son denetimin bulduğu şey, alan adı sahibinin harekete geçebileceği sözcüklerle. Son denetim geçtiyse ya da henüz hiç denetim çalışmadıysa null. Bir ya da iki denetimde başarısız olan bir host hâlâ `active` olabilir ve nedenini burada taşır.
storage nesnesi
Dosya alan adı storage içinde bildirilir ve alan alan tracking ile aynıdır. Yalnızca adın ne için kullanıldığı farklıdır: orada active, alan adından gönderilen dosyaların indirme bağlantılarının onu gösterdiği anlamına gelir.
hoststring | null- Dosya alan adı; alan adının dosya alan adı yoksa null.
status'none' | 'pending' | 'active' | 'failed'- `none`, hiçbir dosya alan adının ayarlanmadığı anlamına gelir. `pending`, biri ayarlanmış ama hiç denetim geçmemiş demektir. `active`, yeni postaların onu kullandığı anlamına gelir. `failed`, daha önce bir denetim geçtiğini ve o zamandan beri kullanımdan çıktığını gösterir.
activeboolean- Tam olarak `status` `active` iken true olur; yani alan adından gönderilen dosyaların indirme bağlantıları host'u kullandığında.
targetstring- CNAME kaydının işaret ettiği, yalnızca bu dosya alan adı için hazırlanmış adres. `host` null olduğu sürece ve yeni bir host'un adresi hâlâ hazırlanırken boş bir dizedir.
record{ type: 'CNAME'; name: string; value: string } | null- Yayımlanacak kayıt: adı `host`, değeri `target` olur. Dosya alan adı yokken ve yeni bir host'un adresi hâlâ hazırlanırken null olur.
checkedAtstring | null- Host'un en son ne zaman denetlendiği, ISO-8601. İlk denetime kadar null.
verifiedAtstring | null- Bir denetimin en son ne zaman geçtiği, ISO-8601. Hiç denetim geçmemiş bir host için null.
errorstring | null- Son denetimin bulduğu şey, alan adı sahibinin harekete geçebileceği sözcüklerle. Son denetim geçtiyse ya da henüz hiç denetim çalışmadıysa null. Bir ya da iki denetimde başarısız olan bir host hâlâ `active` olabilir ve nedenini burada taşır.
Host nasıl denetlenir
İki ad da aynı takvimle denetlenir ve her biri kendi başına denetlenir.
- Henüz denetim geçmemiş bir host ilk saatinde her 2 dakikada, ilk gününde her 10 dakikada, ilk haftasında saatte bir ve ondan sonra 6 saatte bir denetlenir.
- Etkin bir host her 10 dakikada bir denetlenir; üzerindeki başarısız bir denetim 1 dakika sonra, ardından 2 dakika sonra yeniden denenir.
- Etkin bir host, üst üste üç denetim başarısız olduğunda ya da geçtiği son denetimin üzerinden 2 saatten fazla geçtiğinde kullanılmayı bırakır. Yeni postalar o zaman varsayılan host'a döner ve bir denetim yeniden geçene kadar
statusfailedokunur. Denetimler her seferinde biraz daha seyrek ve en çok bir saat arayla sürer.
İzleme alan adı yalnızca izleme yollarını, dosya alan adı yalnızca indirme yollarını sunar ve her biri yalnızca kendisine sahip olan çalışma alanının gönderdiği postalar için yanıt verir.
Hatalar
| Durum | type | code | Ne zaman |
|---|---|---|---|
| 400 | invalid_request_error | malformed_json | Gövde geçerli JSON değil. |
| 403 | permission_error | insufficient_scope | Anahtar domains:write taşımıyor. |
| 404 | not_found_error | resource_not_found | Bu çalışma alanında bu id'ye sahip bir alan adı yok. |
| 409 | conflict_error | domain_not_verified | receiving.verified false iken ve alan adının _openemail-challenge TXT kaydı henüz yayımlanmamışken yeni bir host gönderildi. param, değerin geldiği alandır: trackingHost ya da storageHost. |
| 409 | conflict_error | tracking_host_in_use | Başka bir alan adı host'u zaten kendi izleme alan adı olarak kullanıyor, host zaten dosya alan adı olarak kullanımda ya da alan adının izleme alan adı başka bir OpenEmail sunucusu tarafından yönetiliyor. param değeri trackingHost. |
| 409 | conflict_error | storage_host_in_use | Dosya alan adı için aynı üç durum: başka bir alan adı host'u zaten kendi dosya alan adı olarak kullanıyor, host zaten izleme alan adı olarak kullanımda ya da buradaki dosya alan adı başka bir OpenEmail sunucusu tarafından yönetiliyor. param değeri storageHost. |
| 422 | validation_error | invalid_tracking_host | Host geçerli bir ana makine adı değil ya da izin verilmiyor: alan adının doğrudan bir alt alan adı olmalı; dönüş yolu host'u bounce.<domain>, OpenEmail'e ait bir ad veya posta almak üzere kurulmuş bir alan adı olamaz. param değeri trackingHost. |
| 422 | validation_error | invalid_storage_host | Aynı kurallar, dosya alan adında reddedilir. param değeri storageHost. |
| 422 | validation_error | unknown_parameter | trackingHost ve storageHost dışında bir gövde anahtarı. |
| 422 | validation_error | invalid_parameter | Gövde bir JSON nesnesi değil ya da gönderilen bir alan ne dize ne de null ya da 512 karakteri aşıyor. İki alanı da taşımayan bir gövde hata değildir: hiçbir şeyi değiştirmez ve 200 ile döner. |
| 422 | validation_error | capability_unsupported | Anahtar, bu alan adının tamamına değil tek tek adreslere daraltılmış; oysa iki ad da alan adındaki her adres için geçerli. Alan adını domainAllowlist içinde taşıyan bir anahtar bunları ayarlayabilir. param değeri domainAllowlist. |