Aktualizowanie domeny
Ustawia, sprawdza ponownie lub usuwa własną domenę śledzącą i własną domenę plików domeny — dwie rzeczy, które to API może w domenie zmienić.
Uruchamia prawdziwe wywołanie na twojej przestrzeni roboczej, twoim własnym kluczem.
PATCH /domains/{id}
Ustawia, sprawdza ponownie lub usuwa własną domenę śledzącą i własną domenę plików domeny — dwie rzeczy, które to API może w domenie zmienić.
Żądanie
Domena może mieć jedną własną domenę śledzącą i jedną własną domenę plików — każda to wybrana przez Ciebie jej subdomena, na przykład links.acme.com i files.acme.com — od chwili, gdy jest zweryfikowana albo gdy opublikowano jej rekord TXT _openemail-challenge. Nie musi jeszcze odbierać poczty. Ustawienie takiej nazwy przygotowuje adres przeznaczony wyłącznie dla niej, zgłaszany w target, a record to rekord CNAME kierujący nazwę na ten adres. Gdy sprawdzenie przejdzie, śledzone linki i piksel otwarcia w nowej poczcie z domeny używają https://links.acme.com/t/..., a linki pobierania plików wysłanych z niej używają https://files.acme.com/f/..., zamiast domyślnego hosta.
Parametry
trackingHoststring | null- Subdomena używana do śledzonych linków i piksela otwarcia, najwyżej 512 znaków. Jest przycinana i zamieniana na małe litery, a wiodące `https://` lub `http://`, ścieżka i kropka na końcu są usuwane przed sprawdzeniem. Nowa wartość zastępuje obecną domenę śledzącą, obecna wartość uruchamia sprawdzenie ponownie, `null` lub pusty ciąg ją usuwa, a pominięcie pola zostawia ją bez zmian.
storageHoststring | null- Subdomena używana do linków pobierania plików, czyszczona tak samo i ograniczona do tych samych 512 znaków. Nowa wartość zastępuje obecną domenę plików, obecna wartość uruchamia sprawdzenie ponownie, `null` lub pusty ciąg ją usuwa, a pominięcie pola zostawia ją bez zmian.
Treść żądania jest surowa co do kluczy i swobodna co do ich liczby. Każdy klucz inny niż trackingHost i storageHost daje 422 unknown_parameter, a treść niosąca żaden z nich to operacja pusta, która odpowiada 200 z domeną w obecnym stanie. Oba mogą pójść w jednym wywołaniu i są stosowane po kolei, najpierw trackingHost: odrzucony trackingHost zatrzymuje wywołanie, zanim storageHost zostanie ruszony, a odrzucony storageHost zostawia już wprowadzoną zmianę trackingHost na miejscu. Wysyłaj je osobno, gdy któreś ma się obronić samo.
Ustawianie domeny śledzącej i domeny plików
Wymaga domains:write. Każdy host jest w tym samym wywołaniu walidowany, zapisywany i sprawdzany, więc odpowiedź niesie już wynik tego pierwszego sprawdzenia. Treść jest ta sama co w 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"}Opublikuj tracking.record i storage.record u swojego dostawcy DNS jako zwykłe rekordy CNAME, z wyłączonym proxy. Sprawdzenie rozwiązuje każdą nazwę, a potem pyta https://links.acme.com/t/v/<nonce> lub https://files.acme.com/f/v/<nonce> o odpowiedź podpisaną przez OpenEmail. Przekierowanie nie przechodzi sprawdzenia, podobnie jak może go nie przejść proxy postawione przed nazwą.
Gdy rekord już się rozwiązuje, sprawdzenie może zgłosić, że nazwa wskazuje na OpenEmail i czeka na włączenie. To wystawianie jej certyfikatu HTTPS, które dzieje się po naszej stronie, nie wymaga niczego od Ciebie i może chwilę potrwać. Po jego zakończeniu pierwsze sprawdzenie, które przejdzie, ustawia status na active.
Jeśli adresu nie udało się przygotować w trakcie wywołania, record jest null, target to pusty ciąg, a error mówi, że trwa przygotowanie. Kończy się ono w ciągu kilku minut bez kolejnego wywołania, więc po rekord odczytaj domenę ponownie przez GET /domains/{id}.
Obie nazwy są niezależne. Wywołanie niosące jedno pole zostawia drugi obiekt dokładnie takim, jaki był, więc późniejsze skonfigurowanie plików nigdy nie narusza działającej już domeny śledzącej.
Ponowne sprawdzenie lub usunięcie
Wyślij host, który domena już ma, aby uruchomić sprawdzenie teraz, zamiast czekać na kolejne zaplanowane. Jeśli ostatnie sprawdzenie — zaplanowane czy nie — odbyło się mniej niż 30 sekund temu, wywołanie zwraca zapisany stan bez zmian. Wyślij w polu null, aby usunąć daną nazwę, i pomiń drugie pole, aby zachować nazwę, którą trzyma.
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}Linki w już wysłanej poczcie zachowują host, z którym poszły, i dotyczy to linku pobierania pliku tak samo jak linku śledzonego. Po usunięciu lub zmianie nazwy te linki działają dalej tak długo, jak długo stary rekord CNAME pozostaje na miejscu. Ponowne skonfigurowanie nazwy może dać jej inny record, więc opublikuj ten, który zgłasza odpowiedź.
Obiekt tracking
hoststring | null- Domena śledząca albo null, gdy domena jej nie ma.
status'none' | 'pending' | 'active' | 'failed'- `none` oznacza, że nie ustawiono żadnej domeny śledzącej. `pending` oznacza, że jest ustawiona i nigdy nie przeszła sprawdzenia. `active` oznacza, że nowa poczta jej używa. `failed` oznacza, że wcześniej przeszła sprawdzenie, a od tego czasu wyszła z użycia.
activeboolean- True dokładnie wtedy, gdy `status` to `active`, czyli gdy śledzone linki i piksel otwarcia w nowej poczcie z domeny używają tego hosta.
targetstring- Adres, na który wskazuje rekord CNAME, przygotowany wyłącznie dla tej domeny śledzącej. Jest pustym ciągiem, dopóki `host` jest null, oraz dopóki trwa przygotowywanie adresu dla nowego hosta.
record{ type: 'CNAME'; name: string; value: string } | null- Rekord do opublikowania, nazwany według `host`, z `target` jako wartością. Null, gdy nie ma domeny śledzącej, oraz dopóki trwa przygotowywanie adresu dla nowego hosta.
checkedAtstring | null- Kiedy host był ostatnio sprawdzany, ISO-8601. Null do pierwszego sprawdzenia.
verifiedAtstring | null- Kiedy sprawdzenie ostatnio przeszło, ISO-8601. Null dla hosta, który nigdy żadnego nie przeszedł.
errorstring | null- Co wykazało ostatnie sprawdzenie, słowami, na których właściciel domeny może się oprzeć. Null, gdy ostatnie sprawdzenie przeszło albo gdy żadne jeszcze nie zostało wykonane. Host, który nie przeszedł jednego czy dwóch sprawdzeń, nadal jest `active` i niesie tutaj przyczynę.
Obiekt storage
Domena plików raportuje do storage, pole w pole tak samo jak tracking. Różni się tylko to, do czego nazwa służy: active oznacza tam, że linki pobierania plików wysłanych z domeny wskazują na nią.
hoststring | null- Domena plików albo null, gdy domena jej nie ma.
status'none' | 'pending' | 'active' | 'failed'- `none` oznacza, że nie ustawiono żadnej domeny plików. `pending` oznacza, że jest ustawiona i nigdy nie przeszła sprawdzenia. `active` oznacza, że nowa poczta jej używa. `failed` oznacza, że wcześniej przeszła sprawdzenie, a od tego czasu wyszła z użycia.
activeboolean- True dokładnie wtedy, gdy `status` to `active`, czyli gdy linki pobierania plików wysłanych z domeny używają tego hosta.
targetstring- Adres, na który wskazuje rekord CNAME, przygotowany wyłącznie dla tej domeny plików. Jest pustym ciągiem, dopóki `host` jest null, oraz dopóki trwa przygotowywanie adresu dla nowego hosta.
record{ type: 'CNAME'; name: string; value: string } | null- Rekord do opublikowania, nazwany według `host`, z `target` jako wartością. Null, gdy nie ma domeny plików, oraz dopóki trwa przygotowywanie adresu dla nowego hosta.
checkedAtstring | null- Kiedy host był ostatnio sprawdzany, ISO-8601. Null do pierwszego sprawdzenia.
verifiedAtstring | null- Kiedy sprawdzenie ostatnio przeszło, ISO-8601. Null dla hosta, który nigdy żadnego nie przeszedł.
errorstring | null- Co wykazało ostatnie sprawdzenie, słowami, na których właściciel domeny może się oprzeć. Null, gdy ostatnie sprawdzenie przeszło albo gdy żadne jeszcze nie zostało wykonane. Host, który nie przeszedł jednego czy dwóch sprawdzeń, nadal jest `active` i niesie tutaj przyczynę.
Jak sprawdzany jest host
Obie nazwy są sprawdzane według tego samego harmonogramu, a każda sprawdzana jest osobno.
- Host, który nie przeszedł jeszcze sprawdzenia, jest sprawdzany co 2 minuty przez pierwszą godzinę, co 10 minut przez pierwszą dobę, co godzinę przez pierwszy tydzień i co 6 godzin później.
- Aktywny host jest sprawdzany co 10 minut, a nieudane sprawdzenie ponawiane jest po 1 minucie, a potem po 2.
- Aktywny host przestaje być używany po trzech nieudanych sprawdzeniach z rzędu albo gdy jego ostatnie udane sprawdzenie jest starsze niż 2 godziny. Nowa poczta wraca wtedy do domyślnego hosta, a
statuspokazujefailed, dopóki jakieś sprawdzenie znów nie przejdzie. Sprawdzenia trwają dalej, za każdym razem rzadziej, ale nie rzadziej niż raz na godzinę.
Domena śledząca obsługuje wyłącznie ścieżki śledzenia, a domena plików wyłącznie ścieżki pobierania, i każda odpowiada tylko za pocztę wysłaną przez przestrzeń roboczą, do której należy.
Błędy
| Status | type | code | Kiedy |
|---|---|---|---|
| 400 | invalid_request_error | malformed_json | Treść żądania nie jest prawidłowym JSON-em. |
| 403 | permission_error | insufficient_scope | Klucz nie ma domains:write. |
| 404 | not_found_error | resource_not_found | Brak domeny o tym id w tej przestrzeni roboczej. |
| 409 | conflict_error | domain_not_verified | Wysłano nowy host, gdy receiving.verified jest false, a rekord TXT _openemail-challenge domeny nie został jeszcze opublikowany. param to pole, w którym host przyszedł, trackingHost albo storageHost. |
| 409 | conflict_error | tracking_host_in_use | Inna domena używa już tego hosta jako swojej domeny śledzącej, host jest już w użyciu jako domena plików albo domeną śledzącą tej domeny zarządza inny serwer OpenEmail. param to trackingHost. |
| 409 | conflict_error | storage_host_in_use | Te same trzy przypadki dla domeny plików: inna domena używa już tego hosta jako swojej domeny plików, host jest już w użyciu jako domena śledząca albo tutejszą domeną plików zarządza inny serwer OpenEmail. param to storageHost. |
| 422 | validation_error | invalid_tracking_host | Host nie jest prawidłową nazwą hosta albo jest niedozwolony: musi być ścisłą subdomeną domeny i nie może być hostem ścieżki zwrotnej bounce.<domain>, nazwą należącą do OpenEmail ani domeną skonfigurowaną do odbierania poczty. param to trackingHost. |
| 422 | validation_error | invalid_storage_host | Te same reguły, odrzucenie na domenie plików. param to storageHost. |
| 422 | validation_error | unknown_parameter | Klucz w treści żądania inny niż trackingHost i storageHost. |
| 422 | validation_error | invalid_parameter | Treść żądania nie jest obiektem JSON, obecne pole nie jest ani typu string, ani null, albo przekracza 512 znaków. Treść, która nie niesie żadnego z pól, nie jest błędem: niczego nie zmienia i wraca z 200. |
| 422 | validation_error | capability_unsupported | Klucz jest zawężony do pojedynczych adresów, a nie do całej tej domeny, a obie nazwy dotyczą każdego adresu w domenie. Ustawić je może klucz, który trzyma tę domenę w domainAllowlist. param to domainAllowlist. |