SDK

Dominis

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

Tots els mètodes

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 })

Rebre i enviar són dos fets independents i es retornen com dos objectes. receiving.verified vol dir que l'MX del domini porta el seu correu aquí i que el seu repte de propietat està publicat. sending informa de la comprovació de signatura de sortida: status és verified, pending, failed, no_identity o unknown, i canSend diu si ara mateix s'acceptaria un enviament des del domini. Un veredicte negatiu de més d'un dia es tracta com a desconegut i no pas com un rebuig, així que ramifica segons canSend i no segons status.

update defineix, torna a comprovar o elimina el domini de seguiment personalitzat del domini, un subdomini com ara links.acme.com, i es resol en el mateix DomainDetailResource que get. tracking n'informa a cada lectura. Fins que no passa una comprovació, tracking.status és pending i els enllaços amb seguiment i el píxel d'obertura continuen fent servir l'amfitrió d'OpenEmail per defecte. Quan n'hi passa una, és active i el correu nou del domini fa servir el domini de seguiment per a tots dos.

get també llista les adreces del domini. addresses.list() és la crida relacionada: totes les adreces que AQUESTA CLAU pot posar en una capçalera From, que és més restrictiu.

Paràmetres: domains.get

domainIdstringobligatori: L'id de `domains.list`, un UUID encunyat quan es va afegir el domini, no pas el nom d'amfitrió, de manera que `get('example.com')` no troba res. La cerca està limitada a la connexió de la mateixa clau, a més de l'id, així que el domini d'un altre espai de treball és un 404 i no pas un 403.

Paràmetres: domains.update

idstringobligatori: El mateix id de domini que pren `get`. `domains:write` és l'scope que necessita.
patch.trackingHoststring | nullobligatori: Un subdomini del domini, de com a màxim 512 caràcters, com ara `links.acme.com`. S'escapça i es passa a minúscules, i se n'eliminen un `https://` o `http://` inicial, un camí i un punt final. Un valor nou es valida, es desa i es comprova en la mateixa crida. El valor que el domini ja té torna a executar la comprovació, tret que l'última s'hagi fet fa menys de 30 segons. `null` o una cadena buida elimina el domini de seguiment.

Un amfitrió rebutjat llança un OpenEmailApiError que anomena trackingHost a param: 422 invalid_tracking_host per a un nom que no es pot fer servir, com ara un de fora del domini, 409 domain_not_verified per a un amfitrió nou mentre receiving.verified sigui fals i el registre TXT _openemail-challenge del domini encara no estigui publicat, i 409 tracking_host_in_use per a un nom que ja fa servir un altre domini, o quan el domini de seguiment el gestiona un altre servidor d'OpenEmail. Una clau limitada a adreces concretes rep un 422 capability_unsupported, perquè un domini de seguiment s'aplica a totes les adreces del domini.

Resposta: DomainDetailResource

object'domain': Sempre la cadena `domain`, tant a les files de `list` com en aquesta.
idstring: L'UUID del domini. Estable durant tota la vida de la fila, i l'únic identificador que accepten les altres crides de domini.
domainstring: El nom d'amfitrió nu, en minúscules: `example.com`. Únic a tot el producte, un sol propietari per domini, de manera que dos espais de treball no el poden reclamar tots dos.
receiving.verifiedboolean: Cert quan el DNS ha mostrat que l'MX del domini anomena un amfitrió que porta el seu correu aquí i, quan la fila porta un testimoni de repte, el registre TXT `_openemail-challenge` corresponent. L'MX tot sol no demostra res, ja que tots els dominis per als quals rebem correu publiquen els mateixos noms d'amfitrió, que és per això que existeix el testimoni, i per això aquesta bandera és la porta que el lliurament d'entrada comprova abans d'acceptar correu.
receiving.verifiedAtstring | null: Quan es va superar la verificació, ISO-8601. Null mentre no s'hagi superat, i `verified` es deriva exactament d'aquesta columna, de manera que els dos no poden discrepar mai.
receiving.catchAllboolean: Si s'accepta qualsevol local-part. Activat per defecte per als dominis afegits d'ençà que això és la norma; amb l'opció desactivada només s'accepten les adreces anomenades al domini i la resta es rebutgen en temps d'SMTP, de manera que el remitent rep un rebot i no pas silenci.
receiving.lastCheckedAtstring | null: Quan es va consultar el DNS sobre aquest domini per última vegada. Null vol dir que no s'ha mirat mai, cosa que per a algú que ha afegit un domini fa un minut es llegeix molt diferent d'una fallada. Aquest endpoint informa del resultat desat i no executa mai cap comprovació pròpia.
receiving.errorstring | null: Per què no va passar l'última comprovació, amb paraules sobre les quals el propietari pot actuar: `No MX records yet. DNS changes can take a few minutes to spread.` n'és un cas típic. Null quan passa, i desat en comptes de derivat perquè una recàrrega i la recomprovació programada diguin el mateix.
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown': L'estat de la signatura de sortida tal com el va veure l'última comprovació. Es llegeix de la comprovació desada i no es sondeja en aquesta sol·licitud, de manera que `sending.checkedAt` diu quina antiguitat té.
sending.canSendboolean: Si ara mateix s'acceptaria un enviament des d'aquest domini. Un veredicte negatiu de més d'un dia es tracta com a desconegut i no pas com un rebuig, de manera que això pot ser cert mentre `status` és `pending`. Ramifica segons això abans d'un enviament: un valor fals vol dir que `emails.send` des d'aquest domini es rebutja amb un 409 `domain_not_sendable`.
sending.checkedAtstring | null: Quan es va comprovar per última vegada l'estat de signatura, ISO-8601. Null vol dir mai, que es llegeix molt diferent d'una fallada.
sending.errorstring | null: L'última fallada de signatura explicada amb paraules, o null quan passa la comprovació.
sending.notestring: Una de cinc frases, triada per `sending.status`, que explica què vol dir aquell estat amb paraules sobre les quals el propietari d'un domini pot actuar. Prosa perquè la llegeixi una persona. Ramifica segons `sending.canSend` i no segons això.
trackingDomainTracking: El domini de seguiment personalitzat del domini, tant a les files de `list` com en aquesta, i el que canvia `update`.
tracking.hoststring | null: El domini de seguiment, com ara `links.acme.com`, o null quan no n'hi ha cap definit.
tracking.status'none' | 'pending' | 'active' | 'failed': `none` vol dir que no hi ha cap domini de seguiment definit, `pending` vol dir que no ha passat mai cap comprovació, `active` vol dir que el correu nou el fa servir, i `failed` vol dir que abans passava i que des d'aleshores ha deixat de fer-se servir. Un amfitrió actiu deixa de fer-se servir després de tres comprovacions fallides seguides, o quan la seva última comprovació superada té més de 2 hores.
tracking.activeboolean: Cert exactament quan `status` és `active`, que és quan els enllaços amb seguiment i el píxel d'obertura del correu nou del domini fan servir l'amfitrió.
tracking.targetstring: L'adreça a la qual apunta el registre CNAME, preparada només per a aquest domini de seguiment. Una cadena buida mentre `host` sigui null, i mentre encara s'estigui preparant l'adreça per a un amfitrió nou.
tracking.record{ type: 'CNAME'; name: string; value: string } | null: El registre que s'ha de publicar, amb el nom de `host` i amb `target` com a valor. Null quan no hi ha cap domini de seguiment, i mentre encara s'estigui preparant l'adreça per a un amfitrió nou.
tracking.checkedAtstring | null: Quan es va comprovar l'amfitrió per última vegada, ISO-8601. Null fins a la primera comprovació.
tracking.verifiedAtstring | null: Quan va passar una comprovació per última vegada, ISO-8601. Null per a un amfitrió que no n'ha passada mai cap.
tracking.errorstring | null: Què va trobar l'última comprovació, amb paraules sobre les quals el propietari del domini pot actuar. Null quan l'última comprovació va passar o quan encara no se n'ha executat cap. Un amfitrió que ha fallat una o dues comprovacions encara és `active` i porta el motiu aquí.
addressesArray<{ address: string; enabled: boolean }>: Totes les files d'adreça del domini, que és el que `get` afegeix respecte d'una fila de `list`. Inclou les files que el lliurament va escriure ell mateix sota catch-all, i aquestes deixen de ser acceptades en el moment que es desactiva el catch-all, de manera que l'array no és una llista del que rebrà correu.
addresses[].addressstring: L'adreça completa, reconstruïda a partir de la local-part desada i el nom d'amfitrió i passada a minúscules, de manera que sempre coincideix amb el `domain` de més amunt en comptes de desviar-se'n.
addresses[].enabledboolean: Fals desactiva l'adreça, i una de desactivada es rebutja fins i tot amb el catch-all activat. Totes les files es llisten igualment, així que filtra per això en comptes de llegir l'array com el conjunt d'adreces que funcionen.
createdAtstring: Quan es va afegir la fila del domini, ISO-8601. No pas quan es va verificar: això és `receiving.verifiedAt`, que pot ser null mentre aquest camp té valor.