SDK

Domény

`domains.list`, `get` a `update`.

Všechny 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 })

Příjem a odesílání jsou dvě nezávislé skutečnosti a vracejí se jako dva objekty. receiving.verified znamená, že MX domény sem přivádí její poštu a že je publikována výzva prokazující vlastnictví. sending hlásí kontrolu podepisování odchozí pošty: status je verified, pending, failed, no_identity nebo unknown a canSend říká, zda by odeslání z domény bylo právě teď přijato. Záporný verdikt starší než den se považuje za neznámý, ne za odmítnutí, takže se větvete podle canSend, ne podle status.

update nastavuje, znovu kontroluje nebo odstraňuje vlastní sledovací doménu dané domény, tedy subdoménu jako links.acme.com, a vyhodnotí se na stejný DomainDetailResource jako get. tracking ji hlásí při každém čtení. Dokud kontrola neprojde, je tracking.status roven pending a sledované odkazy i pixel pro měření otevření dál používají výchozího hostitele OpenEmail. Jakmile jedna projde, je active a nová pošta z domény používá pro obojí sledovací doménu.

get také vypíše adresy na doméně. Souvisejícím voláním je addresses.list(): každá adresa, kterou TENTO KLÍČ smí vložit do hlavičky From, což je užší množina.

Parametry: domains.get

domainIdstringpovinné: Id z `domains.list`, tedy UUID vytvořené při přidání domény, ne hostname, takže `get('example.com')` nenajde nic. Vyhledávání je omezeno nejen na id, ale i na vlastní připojení klíče, takže doména jiného pracovního prostoru je 404, ne 403.

Parametry: domains.update

idstringpovinné: Totéž id domény, jaké přijímá `get`. Potřebný scope je `domains:write`.
patch.trackingHoststring | nullpovinné: Subdoména dané domény, nejvýše 512 znaků, například `links.acme.com`. Ořežou se okrajové mezery, převede se na malá písmena a odstraní se úvodní `https://` nebo `http://`, cesta a koncová tečka. Nová hodnota se v témže volání zvaliduje, uloží a zkontroluje. Hodnota, kterou doména už má, spustí kontrolu znovu, pokud poslední neproběhla před méně než 30 sekundami. `null` nebo prázdný řetězec sledovací doménu odstraní.

Odmítnutý hostitel vyhodí OpenEmailApiError s trackingHost v param: 422 invalid_tracking_host pro název, který nelze použít, například název mimo danou doménu, 409 domain_not_verified pro nového hostitele, dokud je receiving.verified false a TXT záznam domény _openemail-challenge ještě není publikován, a 409 tracking_host_in_use pro název, který už používá jiná doména, nebo když sledovací doménu spravuje jiný server OpenEmail. Klíč omezený na konkrétní adresy dostane 422 capability_unsupported, protože sledovací doména platí pro každou adresu na doméně.

Odpověď: DomainDetailResource

object'domain': Vždy řetězec `domain`, stejně na řádcích z `list` jako na tomto.
idstring: UUID domény. Stabilní po celou dobu života řádku a jediný identifikátor, který ostatní volání nad doménami přijímají.
domainstring: Samotné hostname, malými písmeny: `example.com`. Jedinečné napříč celým produktem, jeden vlastník na doménu, takže si ji nemohou nárokovat dva pracovní prostory zároveň.
receiving.verifiedboolean: True, jakmile DNS ukázal u domény MX odkazující na hostitele, který sem její poštu přivádí, a tam, kde záznam nese ověřovací token, i odpovídající TXT záznam `_openemail-challenge`. Samotné MX nedokazuje nic, protože každá doména, pro kterou poštu přijímáme, publikuje stejná jména hostitelů; proto ten token existuje a proto je tento příznak branou, kterou příchozí doručování kontroluje, než poštu přijme.
receiving.verifiedAtstring | null: Kdy ověření prošlo, ISO-8601. Null, dokud neprošlo; `verified` se odvozuje přesně z tohoto sloupce, takže se ty dvě hodnoty nikdy nemohou rozejít.
receiving.catchAllboolean: Zda se přijímá libovolná local-part. U domén přidaných od doby, kdy se to stalo pravidlem, je to zapnuté; s vypnutým nastavením se přijímají jen adresy na doméně výslovně uvedené a zbytek je odmítnut už při SMTP, takže odesílatel dostane bounce místo ticha.
receiving.lastCheckedAtstring | null: Kdy byl na tuto doménu naposledy dotázán DNS. Null znamená, že se nikdy nehledalo, což pro někoho, kdo doménu přidal před minutou, vyznívá úplně jinak než selhání. Tento endpoint hlásí uložený výsledek a nikdy sám kontrolu nespouští.
receiving.errorstring | null: Proč poslední kontrola neprošla, slovy, podle kterých se vlastník může zařídit: typicky třeba `No MX records yet. DNS changes can take a few minutes to spread.` Null, jakmile kontrola projde; je uložené, ne odvozené, takže znovunačtení i naplánovaná opakovaná kontrola říkají totéž.
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown': Stav podepisování odchozí pošty tak, jak jej viděla poslední kontrola. Čte se z uložené kontroly, nezjišťuje se při tomto požadavku, takže `sending.checkedAt` říká, jak je stará.
sending.canSendboolean: Zda by odeslání z této domény bylo právě teď přijato. Záporný verdikt starší než den se považuje za neznámý, ne za odmítnutí, takže tohle může být true, zatímco `status` je `pending`. Před odesláním se větvete podle toho: false znamená, že `emails.send` z této domény skončí odmítnutím 409 `domain_not_sendable`.
sending.checkedAtstring | null: Kdy byl stav podepisování naposledy zkontrolován, ISO-8601. Null znamená nikdy, což se čte velmi odlišně od selhání.
sending.errorstring | null: Poslední selhání podepisování slovy, nebo null, jakmile kontrola projde.
sending.notestring: Jedna z pěti vět, vybraná podle `sending.status`, která říká, co ten stav znamená, slovy, podle nichž může majitel domény jednat. Text pro člověka. Větvete se podle `sending.canSend`, ne podle tohoto.
trackingDomainTracking: Vlastní sledovací doména dané domény, stejně na řádcích z `list` jako na tomto, a to, co mění `update`.
tracking.hoststring | null: Sledovací doména, například `links.acme.com`, nebo null, když žádná není nastavena.
tracking.status'none' | 'pending' | 'active' | 'failed': `none` znamená, že není nastavena žádná sledovací doména, `pending` znamená, že nikdy neprošla kontrolou, `active` znamená, že ji nová pošta používá, a `failed` znamená, že dříve prošla a od té doby se přestala používat. Aktivní hostitel vypadne po třech neúspěšných kontrolách za sebou, nebo jakmile je jeho poslední úspěšná kontrola starší než 2 hodiny.
tracking.activeboolean: True právě tehdy, když je `status` roven `active`, tedy když sledované odkazy a pixel pro měření otevření v nové poště z domény tohoto hostitele používají.
tracking.targetstring: Adresa, na kterou ukazuje záznam CNAME, připravená výhradně pro tuto sledovací doménu. Prázdný řetězec, dokud je `host` null, a dokud se adresa pro nového hostitele teprve připravuje.
tracking.record{ type: 'CNAME'; name: string; value: string } | null: Záznam, který se má publikovat, pojmenovaný podle `host` a s `target` jako hodnotou. Null, když žádná sledovací doména není, a dokud se adresa pro nového hostitele teprve připravuje.
tracking.checkedAtstring | null: Kdy byl hostitel naposledy zkontrolován, ISO-8601. Null až do první kontroly.
tracking.verifiedAtstring | null: Kdy naposledy kontrola prošla, ISO-8601. Null u hostitele, kterému nikdy neprošla.
tracking.errorstring | null: Co poslední kontrola zjistila, slovy, podle nichž může majitel domény jednat. Null, když poslední kontrola prošla nebo když zatím žádná neproběhla. Hostitel, kterému selhala jedna nebo dvě kontroly, je stále `active` a nese důvod zde.
addressesArray<{ address: string; enabled: boolean }>: Každý řádek s adresou na doméně, což je to, co `get` přidává oproti řádku z `list`. Zahrnuje i řádky, které si doručování zapsalo samo v režimu catch-all, a ty přestanou být přijímány v okamžiku, kdy se catch-all vypne, takže toto pole není seznamem toho, co bude přijímat.
addresses[].addressstring: Celá adresa, sestavená z uložené lokální části a hostname a převedená na malá písmena, takže vždy odpovídá `domain` výše, místo aby se od ní odchýlila.
addresses[].enabledboolean: False adresu vypne a vypnutá adresa je odmítnuta, i když je catch-all zapnutý. Každý řádek je vypsán tak jako tak, takže filtrujte podle tohoto, místo abyste pole četli jako množinu funkčních adres.
createdAtstring: Kdy byl záznam domény přidán, ISO-8601. Nikoli kdy proběhlo ověření: to je `receiving.verifiedAt`, které může být null, zatímco tahle hodnota už vyplněná je.