SDK

Domínios

`domains.list`, `get` e `update`.

Todos os métodos

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

A receção e o envio são dois factos independentes e são devolvidos como dois objetos. receiving.verified significa que o MX do domínio encaminha o seu correio para aqui e que o seu desafio de propriedade está publicado. sending reporta a verificação de assinatura de saída: status é verified, pending, failed, no_identity ou unknown, e canSend indica se um envio a partir do domínio seria aceite neste momento. Um veredicto negativo com mais de um dia é tratado como desconhecido e não como uma recusa, por isso baseie a lógica em canSend e não em status.

update define, volta a verificar ou remove o domínio de rastreio personalizado do domínio, um subdomínio como links.acme.com, e resolve para o mesmo DomainDetailResource que get. tracking indica-o em todas as leituras. Até uma verificação ser bem-sucedida, tracking.status é pending e as ligações rastreadas e o píxel de abertura continuam a usar o host predefinido do OpenEmail. Depois de uma ser bem-sucedida, passa a active e o novo correio do domínio usa o domínio de rastreio para ambos.

get também lista os endereços do domínio. addresses.list() é a chamada relacionada: todos os endereços que ESTA CHAVE pode colocar num cabeçalho From, o que é mais restrito.

Parâmetros: domains.get

domainIdstringobrigatório: O id de `domains.list`, um UUID gerado quando o domínio foi adicionado, e não o nome do host, pelo que `get('example.com')` não encontra nada. A pesquisa está limitada à conexão da própria chave, além do id, pelo que o domínio de outro espaço de trabalho dá 404 e não 403.

Parâmetros: domains.update

idstringobrigatório: O mesmo id de domínio que `get` recebe. `domains:write` é o âmbito necessário.
patch.trackingHoststring | nullobrigatório: Um subdomínio do domínio, com no máximo 512 caracteres, como `links.acme.com`. São removidos os espaços nas extremidades e o valor é convertido para minúsculas, e um `https://` ou `http://` inicial, um caminho e um ponto final são eliminados. Um novo valor é validado, guardado e verificado na mesma chamada. O valor que o domínio já tem volta a executar a verificação, exceto se a última tiver sido há menos de 30 segundos. `null` ou uma string vazia remove o domínio de rastreio.

Um host recusado lança um OpenEmailApiError com trackingHost em param: 422 invalid_tracking_host para um nome que não pode ser usado, como um fora do domínio, 409 domain_not_verified para um novo host enquanto receiving.verified for false e o registo TXT _openemail-challenge do domínio ainda não estiver publicado, e 409 tracking_host_in_use para um nome que outro domínio já usa, ou quando o domínio de rastreio é gerido por outro servidor OpenEmail. Uma chave limitada a endereços específicos recebe 422 capability_unsupported, porque um domínio de rastreio se aplica a todos os endereços do domínio.

Resposta: DomainDetailResource

object'domain': Sempre a string `domain`, tanto nas linhas de `list` como nesta.
idstring: O UUID do domínio. Estável durante toda a vida da linha, e o único identificador que as outras chamadas de domínio aceitam.
domainstring: O nome do host simples, em minúsculas: `example.com`. Único em todo o produto, um proprietário por domínio, pelo que dois espaços de trabalho não o podem reivindicar em simultâneo.
receiving.verifiedboolean: É true assim que o DNS mostrou o MX do domínio a indicar um host que encaminha o seu correio para aqui e, quando a linha tem um token de desafio, o registo TXT `_openemail-challenge` correspondente. O MX por si só não prova nada, já que todos os domínios para os quais recebemos correio publicam os mesmos nomes de host; é por isso que o token existe, e é por isso que esta flag é a barreira que a entrega de entrada verifica antes de aceitar correio.
receiving.verifiedAtstring | null: Quando a verificação passou, em ISO-8601. É null enquanto não passar, e `verified` é derivado exatamente desta coluna, pelo que os dois nunca podem divergir.
receiving.catchAllboolean: Indica se qualquer parte local é aceite. Ativo por predefinição nos domínios adicionados desde que esta passou a ser a regra; com ele desativado, só são aceites os endereços definidos no domínio e os restantes são rejeitados durante a sessão SMTP, pelo que o remetente recebe uma mensagem de devolução em vez de silêncio.
receiving.lastCheckedAtstring | null: Quando o DNS foi consultado pela última vez sobre este domínio. Null significa que nunca foi consultado, o que se lê de forma muito diferente de uma falha para quem adicionou um domínio há um minuto. Este endpoint reporta o resultado guardado e nunca executa uma verificação própria.
receiving.errorstring | null: Porque é que a última verificação não passou, em termos com que o proprietário possa agir: `No MX records yet. DNS changes can take a few minutes to spread.` é um exemplo típico. É null assim que passar, e é guardado em vez de derivado para que um recarregamento e a nova verificação agendada digam o mesmo.
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown': O estado de assinatura de saída tal como a última verificação o viu. Lido da verificação guardada em vez de sondado neste pedido, pelo que `sending.checkedAt` indica a sua antiguidade.
sending.canSendboolean: Indica se um envio a partir deste domínio seria aceite neste momento. Um veredicto negativo com mais de um dia é tratado como desconhecido e não como uma recusa, pelo que este campo pode ser true enquanto `status` é `pending`. Baseie a lógica neste campo antes de um envio: um valor false significa que `emails.send` a partir deste domínio é recusado com 409 `domain_not_sendable`.
sending.checkedAtstring | null: Quando o estado de assinatura foi verificado pela última vez, em ISO-8601. Null significa nunca, o que se lê de forma muito diferente de uma falha.
sending.errorstring | null: A última falha de assinatura por extenso, ou null assim que a verificação passar.
sending.notestring: Uma de cinco frases, escolhida por `sending.status`, que explica o que esse estado significa em termos com que o proprietário de um domínio possa agir. Texto para uma pessoa ler. Baseie a lógica em `sending.canSend` e não neste campo.
trackingDomainTracking: O domínio de rastreio personalizado do domínio, tanto nas linhas de `list` como nesta, e aquilo que `update` altera.
tracking.hoststring | null: O domínio de rastreio, como `links.acme.com`, ou null quando não há nenhum definido.
tracking.status'none' | 'pending' | 'active' | 'failed': `none` significa que não há domínio de rastreio definido, `pending` significa que nunca passou numa verificação, `active` significa que o novo correio o usa, e `failed` significa que passou antes e entretanto deixou de ser usado. Um host ativo deixa de ser usado após três verificações falhadas seguidas, ou quando a sua última verificação bem-sucedida tem mais de 2 horas.
tracking.activeboolean: É true exatamente quando `status` é `active`, que é quando as ligações rastreadas e o píxel de abertura no novo correio do domínio usam o host.
tracking.targetstring: O endereço para onde aponta o registo CNAME, preparado exclusivamente para este domínio de rastreio. Uma string vazia enquanto `host` for null e enquanto o endereço para um novo host ainda estiver a ser preparado.
tracking.record{ type: 'CNAME'; name: string; value: string } | null: O registo a publicar, com o nome de `host` e `target` como valor. É null quando não há domínio de rastreio e enquanto o endereço para um novo host ainda estiver a ser preparado.
tracking.checkedAtstring | null: Quando o host foi verificado pela última vez, em ISO-8601. É null até à primeira verificação.
tracking.verifiedAtstring | null: Quando uma verificação passou pela última vez, em ISO-8601. É null para um host que nunca passou em nenhuma.
tracking.errorstring | null: O que a última verificação encontrou, em termos com que o proprietário do domínio possa agir. É null quando a última verificação passou ou quando ainda nenhuma foi executada. Um host que falhou uma ou duas verificações continua `active` e apresenta aqui o motivo.
addressesArray<{ address: string; enabled: boolean }>: Todas as linhas de endereço do domínio, que é o que `get` acrescenta em relação a uma linha de `list`. Inclui as linhas que a própria entrega escreveu ao abrigo do catch-all, e essas deixam de ser aceites no momento em que o catch-all é desativado, pelo que o array não é uma lista do que vai receber correio.
addresses[].addressstring: O endereço completo, reconstruído a partir da parte local guardada e do nome do host, e convertido para minúsculas, pelo que corresponde sempre ao `domain` acima em vez de divergir dele.
addresses[].enabledboolean: O valor false desativa o endereço, e um endereço desativado é rejeitado mesmo com o catch-all ativo. Todas as linhas são listadas de qualquer forma, por isso filtre por este campo em vez de ler o array como o conjunto de endereços que funcionam.
createdAtstring: Quando a linha do domínio foi adicionada, em ISO-8601. Não quando foi verificado: isso é `receiving.verifiedAt`, que pode ser null enquanto este está definido.