Domínios
`domains.list`, `list_all`, `iterate`, `get` e `update`.
Todos os métodos
page = client.domains.listpage.items.each { |row| puts "#{row[:domain]} #{row.dig(:sending, :canSend)}" } domain = client.domains.get("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f")puts domain.dig(:receiving, :verified), domain.dig(:sending, :status) domain[:addresses].each do |entry| puts "#{entry[:address]} #{entry[:enabled]}"endA receção e o envio são dois factos independentes e são devolvidos como dois Hashes. 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, lido como domain.dig(:sending, :canSend), e não em status.
list devolve uma OpenEmail::Page de domínios por ordem alfabética, e list_all devolve-os todos num único Array. iterate passa-os um de cada vez a um bloco. Sem bloco, devolve um Enumerator.
domain_id = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" updated = client.domains.update(domain_id, trackingHost: "links.acme.com")puts updated.dig(:tracking, :status), updated.dig(:tracking, :record, :name), updated.dig(:tracking, :record, :value) client.domains.update(domain_id, trackingHost: nil)update define, volta a verificar ou remove o domínio de rastreio personalizado do domínio, um subdomínio como links.acme.com, e devolve o mesmo Hash 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: os endereços que esta chave pode colocar num cabeçalho From, o que é mais restrito, cada um com um veredicto canSend. Devolve uma OpenEmail::AddressBookPage, que os guarda em addresses em vez de items, ao lado de domains e unrestricted. O seu list_all devolve um único OpenEmail::AddressBook.
app_host é um espaço de nomes próprio, client.app_host. get, set, verify e delete leem e alteram o endereço da aplicação web do espaço de trabalho, um subdomínio como mailbox.acme.com num destes domínios ou em qualquer outro domínio que o espaço de trabalho controle, onde a respetiva equipa inicia sessão com a marca do espaço de trabalho. set devolve os registos DNS a publicar, em record e, num domínio fora do espaço de trabalho, em ownershipRecord. delete, e um set que substitui um endereço, pedem um código de verificação a uma aplicação OAuth: enquanto não o tiver, a chamada lança um 403 cujo step_up_required? é true.
branding define essa marca. get lê as ligações para o símbolo, o logótipo, o logótipo para o modo escuro e a foto de início de sessão, os dois tipos de letra e o fundo de início de sessão. update altera os tipos de letra e o fundo, upload_image(variant, data, content_type: nil) carrega uma das quatro imagens e remove_image(variant) remove uma. variant é mark, wordmark, wordmark-dark ou login-background, e OpenEmail::BRAND_IMAGE_VARIANTS nomeia-as. data é uma String binária, um IO ou um Pathname. Um Pathname como Pathname("logo.svg"), um File ou um ficheiro carregado no Rails traz consigo o seu tipo. Outros bytes precisam de content_type:, e uma imagem sem tipo é recusada com um 422 invalid_image. É o logótipo que dá a marca ao endereço da aplicação web e, num plano pago, aos emails enviados pelo espaço de trabalho.
Parâmetros: domains.get
idStringobrigató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 ao próprio espaço de trabalho da chave, além do id, pelo que o domínio de outro espaço de trabalho dá um 404, lançado como `OpenEmail::NotFoundError`, e não um 403. Um id nil ou vazio lança ArgumentError antes de qualquer envio.
Parâmetros: domains.update
idStringobrigatório- O mesmo id de domínio que `get` recebe. `domains:write` é o âmbito necessário.
trackingHostString or nil- 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. Passe nil ou uma String vazia para remover o domínio de rastreio, e omita o campo para o deixar como está.
Um host recusado lança um OpenEmail::ApiError com trackingHost em param: um 422 invalid_tracking_host para um nome que não pode ser usado, como um fora do domínio, um 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 um 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. O 422 chega como OpenEmail::ValidationError e cada 409 como OpenEmail::ConflictError. Uma chave limitada a endereços específicos recebe um 422 capability_unsupported, porque um domínio de rastreio se aplica a todos os endereços do domínio.
As alterações são passadas como argumentos nomeados ou como um único Hash, e os seus campos mantêm os nomes em camelCase da API, por isso tracking_host: é enviado tal como está escrito e recusado com um 422 unknown_parameter. update também aceita catchAll, storageHost para um domínio de ficheiros como files.acme.com, e dmarcPolicy. Todos os campos são opcionais e a referência de métodos descreve cada um. A gem repete update como uma leitura, porque uma repetição encontra o host já definido e, no máximo, volta a verificá-lo.
Resposta: um domínio (domains.get)
objectString- 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 or nil- Quando a verificação passou, como String ISO 8601. É nil 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. Está 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 or nil- Quando o DNS foi consultado pela última vez sobre este domínio. É nil quando o DNS nunca foi consultado, o que se lê de forma muito diferente de uma falha para quem adicionou um domínio há um minuto. Ler um domínio não verificado volta a consultar o DNS quando a última verificação tem mais de 20 segundos, por isso chamar `get` periodicamente é uma forma de esperar pela verificação, e `verify` verifica de imediato.
receiving.errorString or nil- 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. É nil assim que a verificação passar, e é guardado em vez de derivado, pelo que um recarregamento e a nova verificação agendada dizem o mesmo.
sending.statusString- O estado de assinatura de saída tal como a última verificação o viu: `verified`, `pending`, `failed`, `no_identity` ou `unknown`. É lido da verificação guardada, 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 or nil- Quando o estado de assinatura foi verificado pela última vez, como String ISO 8601. É nil quando nunca foi verificado, o que se lê de forma muito diferente de uma falha.
sending.errorString or nil- A última falha de assinatura por extenso, ou nil 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, por isso baseie a lógica em `sending.canSend` e não neste campo.
trackingHash- O domínio de rastreio personalizado do domínio, tanto nas linhas de `list` como nesta, e aquilo que `update` altera.
tracking.hostString or nil- O domínio de rastreio, como `links.acme.com`, ou nil quando não há nenhum definido.
tracking.statusString- `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 pixel de abertura no correio novo do domínio usam o host.
tracking.targetString- O endereço para o qual o registo CNAME aponta, preparado só para este domínio de rastreio. É uma String vazia enquanto `host` for nil, e enquanto o endereço de um host novo ainda estiver a ser preparado.
tracking.recordHash or nil- O registo a publicar, um Hash com `type` (sempre `CNAME`), `name` e `value`, com o nome de `host` e `target` como valor. É nil quando não há domínio de rastreio, e enquanto o endereço de um host novo ainda estiver a ser preparado, por isso `dig(:tracking, :record, :value)` lê-o em segurança.
tracking.checkedAtString or nil- Quando o host foi verificado pela última vez, como String ISO 8601. É nil até à primeira verificação.
tracking.verifiedAtString or nil- Quando uma verificação passou pela última vez, como String ISO 8601. É nil para um host que nunca passou nenhuma.
tracking.errorString or nil- O que a última verificação encontrou, em termos com que o proprietário do domínio possa agir. É nil quando a última verificação passou ou quando ainda não correu nenhuma. Um host que falhou uma ou duas verificações continua `active` e traz aqui o motivo.
addressesArray<Hash>- 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, como String ISO 8601. Não é quando o domínio foi verificado: isso é `receiving.verifiedAt`, que pode ser nil enquanto este está definido.