SDK

Domeny

`domains.list`, `get` i `update`.

Wszystkie metody

usage.ts

const domains = await openemail.domains.list()const domain = await openemail.domains.get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f') console.log(domain.receiving.verified, domain.sending.status)for (const address of domain.addresses) console.log(address.address, address.enabled) const updated = await openemail.domains.update(domain.id, { trackingHost: 'links.acme.com' })console.log(updated.tracking.status, updated.tracking.record?.name, updated.tracking.record?.value) await openemail.domains.update(domain.id, { trackingHost: null })

Odbieranie i wysyłanie to dwa niezależne fakty i są zwracane jako dwa obiekty. receiving.verified znaczy, że MX domeny kieruje jej pocztę tutaj i że opublikowano wyzwanie potwierdzające własność. sending raportuje kontrolę podpisywania wychodzącego: status to verified, pending, failed, no_identity albo unknown, a canSend mówi, czy wysyłka z tej domeny zostałaby teraz przyjęta. Negatywny werdykt starszy niż dzień jest traktowany jako nieznany, a nie jako odmowa, więc rozgałęziaj się na canSend, a nie na status.

update ustawia, ponownie sprawdza albo usuwa własną domenę śledzenia danej domeny, czyli subdomenę taką jak links.acme.com, i rozwiązuje się tym samym DomainDetailResource co get. tracking raportuje ją przy każdym odczycie. Dopóki kontrola nie przejdzie, tracking.status to pending, a śledzone linki i piksel otwarcia dalej używają domyślnego hosta OpenEmail. Gdy kontrola przejdzie, jest active, a nowa poczta z tej domeny używa domeny śledzenia do obu rzeczy.

get wymienia też adresy w domenie. addresses.list() to pokrewne wywołanie: każdy adres, jaki TEN KLUCZ może wstawić w nagłówek From, czyli węższy zbiór.

Parametry: domains.get

domainIdstringwymagane: Identyfikator z `domains.list`, czyli UUID wybity przy dodaniu domeny, a nie nazwa hosta, więc `get('example.com')` niczego nie znajdzie. Wyszukiwanie jest ograniczone do własnego połączenia klucza, nie tylko do identyfikatora, więc domena innej przestrzeni roboczej to 404, a nie 403.

Parametry: domains.update

idstringwymagane: Ten sam identyfikator domeny, który przyjmuje `get`. `domains:write` to wymagany zakres.
patch.trackingHoststring | nullwymagane: Subdomena tej domeny, najwyżej 512 znaków, taka jak `links.acme.com`. Jest przycinana i zamieniana na małe litery, a wiodące `https://` lub `http://`, ścieżka i kropka na końcu są usuwane. Nowa wartość jest walidowana, zapisywana i sprawdzana w tym samym wywołaniu. Wartość, którą domena już ma, uruchamia kontrolę ponownie, chyba że poprzednia była mniej niż 30 sekund temu. `null` albo pusty ciąg usuwa domenę śledzenia.

Odrzucony host rzuca OpenEmailApiError z trackingHost w param: 422 invalid_tracking_host dla nazwy, której nie da się użyć, na przykład spoza domeny, 409 domain_not_verified dla nowego hosta, gdy receiving.verified jest false i rekord TXT _openemail-challenge domeny nie jest jeszcze opublikowany, oraz 409 tracking_host_in_use dla nazwy, której używa już inna domena, albo gdy domeną śledzenia zarządza inny serwer OpenEmail. Klucz ograniczony do konkretnych adresów dostaje 422 capability_unsupported, bo domena śledzenia dotyczy każdego adresu w domenie.

Odpowiedź: DomainDetailResource

object'domain': Zawsze ciąg `domain`, zarówno na wierszach `list`, jak i tutaj.
idstring: UUID domeny. Stabilny przez całe życie wiersza i jedyny uchwyt przyjmowany przez pozostałe wywołania domen.
domainstring: Sama nazwa hosta, małymi literami: `example.com`. Unikalna w całym produkcie, jeden właściciel na domenę, więc dwie przestrzenie robocze nie mogą jej obie zająć.
receiving.verifiedboolean: True, gdy DNS pokazał, że MX domeny nazywa host kierujący jej pocztę tutaj oraz — gdy wiersz niesie token wyzwania — że istnieje pasujący rekord TXT `_openemail-challenge`. Sam MX niczego nie dowodzi, bo każda domena, dla której odbieramy, publikuje te same nazwy hostów; dlatego istnieje token i dlatego ta flaga jest bramką, którą doręczanie przychodzące sprawdza przed przyjęciem poczty.
receiving.verifiedAtstring | null: Kiedy weryfikacja przeszła, ISO-8601. Null, dopóki nie przeszła, a `verified` wywodzi się dokładnie z tej kolumny, więc oba nigdy nie mogą być ze sobą sprzeczne.
receiving.catchAllboolean: Czy przyjmowana jest dowolna część lokalna. Domyślnie włączone dla domen dodanych od czasu, gdy stało się to regułą; przy wyłączonym przyjmowane są tylko adresy nazwane w domenie, a reszta jest odrzucana na poziomie SMTP, więc nadawca dostaje zwrotkę zamiast ciszy.
receiving.lastCheckedAtstring | null: Kiedy ostatnio pytano DNS o tę domenę. Null znaczy: nigdy nie sprawdzano, co dla kogoś, kto dodał domenę minutę temu, czyta się zupełnie inaczej niż porażka. Ten endpoint raportuje zapisany wynik i nigdy nie uruchamia własnej kontroli.
receiving.errorstring | null: Dlaczego ostatnia kontrola nie przeszła, w słowach, na które właściciel może zareagować: typowe jest `No MX records yet. DNS changes can take a few minutes to spread.` Null, gdy przejdzie, i zapisane, a nie wyliczane, więc przeładowanie i zaplanowana ponowna kontrola mówią to samo.
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown': Stan podpisywania wychodzącego taki, jaki zobaczyła ostatnia kontrola. Odczytany z zapisanej kontroli, a nie sondowany przy tym żądaniu, więc `sending.checkedAt` mówi, jak stary jest.
sending.canSendboolean: Czy wysyłka z tej domeny zostałaby teraz przyjęta. Negatywny werdykt starszy niż dzień jest traktowany jako nieznany, a nie jako odmowa, więc to pole może być true, gdy `status` to `pending`. Rozgałęziaj się na nim przed wysyłką: false znaczy, że `emails.send` z tej domeny zostanie odrzucone z 409 `domain_not_sendable`.
sending.checkedAtstring | null: Kiedy ostatnio sprawdzano stan podpisywania, ISO-8601. Null znaczy: nigdy, co czyta się zupełnie inaczej niż porażka.
sending.errorstring | null: Ostatnia porażka podpisywania, słowami, albo null, gdy kontrola przejdzie.
sending.notestring: Jedno z pięciu zdań, wybrane przez `sending.status`, mówiące, co ten stan znaczy w słowach, na które właściciel domeny może zareagować. Proza do czytania przez człowieka. Rozgałęziaj się na `sending.canSend`, a nie na tym.
trackingDomainTracking: Własna domena śledzenia tej domeny, zarówno na wierszach `list`, jak i tutaj, i to, co zmienia `update`.
tracking.hoststring | null: Domena śledzenia, taka jak `links.acme.com`, albo null, gdy żadnej nie ustawiono.
tracking.status'none' | 'pending' | 'active' | 'failed': `none` znaczy, że nie ustawiono domeny śledzenia, `pending` — że nigdy nie przeszła kontroli, `active` — że nowa poczta jej używa, a `failed` — że przechodziła wcześniej, a od tamtej pory wypadła z użycia. Aktywny host wypada po trzech nieudanych kontrolach z rzędu albo gdy ostatnia udana kontrola jest starsza niż 2 godziny.
tracking.activeboolean: True dokładnie wtedy, gdy `status` to `active`, czyli gdy śledzone linki i piksel otwarcia w nowej poczcie z tej domeny używają tego hosta.
tracking.targetstring: Adres, na który wskazuje rekord CNAME, przygotowany wyłącznie dla tej domeny śledzenia. Pusty ciąg, dopóki `host` jest null oraz dopóki adres dla nowego hosta jest jeszcze przygotowywany.
tracking.record{ type: 'CNAME'; name: string; value: string } | null: Rekord do opublikowania, nazwany po `host`, z `target` jako wartością. Null, gdy nie ma domeny śledzenia, oraz gdy adres dla nowego hosta jest jeszcze przygotowywany.
tracking.checkedAtstring | null: Kiedy host był ostatnio sprawdzany, ISO-8601. Null do pierwszej kontroli.
tracking.verifiedAtstring | null: Kiedy kontrola ostatnio przeszła, ISO-8601. Null dla hosta, który nigdy jej nie przeszedł.
tracking.errorstring | null: Co wykazała ostatnia kontrola, w słowach, na które właściciel domeny może zareagować. Null, gdy ostatnia kontrola przeszła albo gdy żadnej jeszcze nie było. Host, który oblał jedną lub dwie kontrole, jest wciąż `active` i niesie tu powód.
addressesArray<{ address: string; enabled: boolean }>: Każdy wiersz adresu w domenie, czyli to, co `get` dodaje ponad wiersz `list`. Obejmuje wiersze zapisane samoczynnie przez doręczanie w trybie catch-all, a te przestają być przyjmowane w chwili wyłączenia catch-all, więc ta tablica nie jest listą tego, co będzie odbierać.
addresses[].addressstring: Pełny adres, odtworzony z zapisanej części lokalnej i nazwy hosta i zapisany małymi literami, więc zawsze pasuje do powyższej `domain`, zamiast od niej odchodzić.
addresses[].enabledboolean: False wyłącza adres, a wyłączony jest odrzucany nawet przy włączonym catch-all. Każdy wiersz jest wymieniony tak czy inaczej, więc filtruj po tym polu, zamiast czytać tablicę jako zbiór działających adresów.
createdAtstring: Kiedy dodano wiersz domeny, ISO-8601. Nie kiedy się zweryfikowała: to jest `receiving.verifiedAt`, które może być null, gdy to pole jest ustawione.