Domínios e endereços

Dois espaços de nomes cobrem os seus domínios. openemail domains gere os domínios associados ao espaço de trabalho: acrescentá-los e removê-los, os registos DNS de que cada um precisa, se pode receber e enviar, o catch-all, os domínios de rastreio e de ficheiros, e os endereços. openemail addresses responde a uma pergunta mais restrita: a partir de que endereços pode enviar a chave ou o início de sessão que está a usar.

• —Um comando de domínio aceita o id do domínio, um UUID de domains list ou domains create. O nome do anfitrião não é aceite em vez dele, por isso openemail domains get acme.com dá 404 e sai com o código 5.
• —Um comando de endereço aceita o id do domínio e depois o id do endereço, um UUID de domains list-addresses ou domains create-address.
• —domain e address também funcionam como nomes de espaço de nomes. Os verbos de domínio respondem aos aliases habituais, como ls, show, new, edit e rm, e o mesmo acontece com addresses list. Os cinco verbos para os endereços de um domínio, como create-address, não têm nenhum.
• —openemail <command> --help lista cada argumento e opção com o tipo, o scope de que a chamada precisa, o método e o caminho, e o que devolve. Acrescente --json para ter a mesma página como dados.

Um domínio indica dois factos independentes. receiving.verified é true assim que o DNS público responde com os seus registos MX e o seu registo TXT _openemail-challenge, e a partir daí recebe correio. sending.status é o estado de assinatura tal como a última verificação o viu: verified, pending, failed, no_identity ou unknown. sending.canSend diz se um envio a partir do domínio seria aceite neste momento, e um veredicto negativo com mais de um dia conta como desconhecido, por isso um script deve decidir com base em canSend e não em status. Enquanto for false, um envio a partir do domínio é recusado com 409 domain_not_sendable.

• —domains create faz a primeira verificação de DNS durante a chamada, por isso cada entrada em records já traz um status: found, missing, ou null quando ainda não foi verificada. Publique cada registo exatamente como é dado, já que os valores são específicos do domínio.
• —domains verify verifica de imediato. Nos 10 segundos seguintes à última verificação não verifica nada de novo e devolve o domínio tal como está. Num domínio verificado volta a verificar os registos de assinatura, por isso sending está atualizado.
• —domains get num domínio não verificado volta a verificar quando a última verificação tem mais de 20 segundos, por isso consultar get periodicamente também funciona e só precisa de domains:read, enquanto verify precisa de domains:write.
• —Um registo publicado há pouco pode demorar alguns minutos a aparecer no DNS público.

Num terminal, get, create e verify mostram um campo por linha, com os blocos aninhados como receiving, sending e records em JSON compacto. Acrescente --json e leia-os com uma ferramenta como jq, como fazem os exemplos abaixo.

domains update altera três definições que não dependem umas das outras. Uma opção que omitir fica como está, e sem nenhuma opção o domínio volta inalterado.

• —Um anfitrião novo é guardado e verificado na mesma chamada. Publique um registo CNAME com o nome record.name e o valor record.value do bloco tracking ou storage da resposta, com qualquer proxy desligado. Configurar um anfitrião de novo pode dar-lhe um valor diferente, por isso publique o que a resposta mais recente indicar.
• —Até passar uma verificação, o anfitrião aparece como pending e o correio novo mantém o anfitrião predefinido do OpenEmail. Quando passa uma, aparece como active. O OpenEmail continua a verificar por si, e um anfitrião ativo que falha três verificações seguidas, ou cuja última verificação bem-sucedida tem 2 horas, aparece como failed enquanto o correio novo volta ao anfitrião predefinido.
• —Remova um anfitrião com null, como em --tracking-host null. Um valor vazio como --tracking-host= é um erro de utilização na CLI e sai com o código 2.
• —Um anfitrião novo precisa do domínio verificado, ou pelo menos do seu registo TXT _openemail-challenge publicado. Caso contrário, a chamada é recusada com 409 domain_not_verified.
• —As opções aplicam-se por ordem: o catch-all, depois o domínio de rastreio e depois o domínio de ficheiros. Uma opção posterior que seja recusada pode deixar guardada uma alteração anterior, por isso envie-as em chamadas separadas quando cada uma tiver de valer por si.

Um domínio contém os endereços criados à mão ou através da API, e os que o seu catch-all apanhou quando lhes chegou correio pela primeira vez. list-addresses mostra os dois tipos, incluindo os desativados. O catch-all em si não é uma linha: é receiving.catchAll no domínio.

• —create-address aceita --local-part, a parte antes da @, e uma --label opcional. O domínio ainda não tem de estar verificado, mas o endereço não recebe nada até estar. * sozinho é recusado, já que é assim que se escreve o catch-all.
• —Criar um endereço que já existe, ou um que foi removido, não é um erro. Volta ativo, com a etiqueta que enviou ou sem nenhuma, e mantém o id. Um endereço que o catch-all apanhou passa a ser um criado à mão, por isso continua a receber depois de o catch-all ser desligado.
• —Com o catch-all ligado, um endereço novo começa com as definições por endereço do catch-all, como a assinatura e o rastreio, exceto as definições de privacidade. São copiadas uma vez e não se mantêm sincronizadas.
• —update-address --no-enabled faz com que o endereço deixe de aceitar correio, por isso os remetentes recebem uma devolução, e não é possível enviar nada a partir dele. Mantém o correio, as definições e as pessoas que lhe têm acesso, e --enabled retoma onde parou. --label muda-lhe o nome, e --label null remove o nome.
• —delete-address vai mais longe. O correio para o endereço é recusado mesmo com o catch-all ligado, o reencaminhamento para, as definições são eliminadas, as pessoas com acesso a ele perdem esse acesso e o início de sessão com palavra-passe é revogado. O correio que já recebeu fica na caixa de correio. Criá-lo de novo recupera o mesmo id, sem as definições nem os acessos anteriores.

openemail addresses list responde à pergunta por trás de um 403 from_address_forbidden: que endereços a chave ou o início de sessão com que está a chamar pode pôr em From. Precisa de emails:send em vez de um scope de leitura, porque descreve o que um envio aceitaria.

• —Num terminal mostra duas tabelas: os endereços, cada um a indicar se está ativo e se pode enviar a partir dele, e depois os domínios, cada um a indicar se está verificado para receber e para enviar, e o seu catch-all.
• —unrestricted é true quando nada restringe a credencial. Nesse caso é possível enviar a partir de qualquer parte local dos domínios do espaço de trabalho, incluindo as que ninguém criou. Caso contrário, canSend só é true para um endereço ativo que a credencial cobre, através de um domínio inteiro que tem ou da sua própria lista de endereços.
• —canSend é false para um endereço desativado, para um que a credencial não cobre e para um cujo domínio ainda não consegue assinar.
• —Só são listados os endereços criados. Uma credencial que tem um domínio inteiro pode na mesma enviar a partir de qualquer parte local dele, e um endereço da sua lista sem caixa de correio por trás pode ser usado para enviar sem aparecer aqui.
• —Com --json mostra { unrestricted, addresses, domains, hasMore, nextCursor } para uma página, e { unrestricted, addresses, domains } com --all, em vez do documento { items, hasMore, nextCursor } que outras listas mostram. Com --all num pipe, ou com --ndjson, mostra um endereço por linha.

openemail status lê o seu início de sessão, addresses list e domains list ao mesmo tempo e mostra-os juntos. A sua tabela Sender addresses mostra cada endereço a indicar se pode enviar e se está ativo. A sua tabela Domains mostra cada domínio como verified ou not verified para a receção, o estado de envio e o catch-all. Mostra os primeiros 100 de cada uma e indica o comando --all para o resto.

• —Uma parte que a sua credencial não pode ler, como os domínios sem domains:read ou os endereços sem emails:send, diz Not available com o motivo, e o resto é mostrado na mesma.
• —Se ainda não houver endereços, sugere openemail domains create --domain example.com.
• —openemail status --json mostra um objeto com account, addresses, domains e unavailable, onde unavailable dá o motivo de cada parte que não foi possível ler.

Ligar um fornecedor de DNS, para que os registos de um domínio novo sejam escritos por si, só se faz na aplicação web em 0.0.2. openemail open providers, ou open dns, abre essa página. open domains abre os domínios e os seus registos DNS, e open addresses os endereços. O reencaminhamento também está na aplicação web, e open forwarding <address> abre-o para um endereço. --print mostra a ligação em vez de abrir um navegador.

openemail domains create --domain acme.com --json > acme.jsonjq -r '.records[] | [.type, .name, .value, (.priority // "")] | @tsv' acme.jsonopenemail domains verify "$(jq -r .id acme.json)"

id=b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6funtil openemail domains get "$id" --json | jq -e .receiving.verified > /dev/null; do  sleep 30doneopenemail domains get "$id" --json | jq '.sending | {status, canSend, error}'

openemail domains list-addresses "$id" --allopenemail domains create-address "$id" --local-part invoices --label Invoicesopenemail domains update "$id" --no-catch-all --dry-runopenemail domains update "$id" --no-catch-all

Criar invoices à mão faz com que continue a receber depois de o catch-all ser desligado, enquanto o correio para qualquer outro endereço que o catch-all apanhou é recusado. A simulação mostra o PATCH e o seu corpo sem o enviar.

openemail domains update "$id" --tracking-host links.acme.com --json | jq '.tracking | {status, record, error}'openemail domains update "$id" --tracking-host null

address_id=$(openemail domains list-addresses "$id" --all | jq -r 'select(.address == "[email protected]") | .id')openemail domains update-address "$id" "$address_id" --no-enabledopenemail domains delete-address "$id" "$address_id" --yes

Desativar primeiro o endereço pode ser anulado com --enabled. A eliminação não, e num script precisa de --yes. Com um início de sessão no navegador também pede um código de verificação, que --yes nunca salta.

openemail domains list --all | jq -r 'select(.sending.canSend | not) | [.domain, .sending.status] | @tsv'openemail addresses list --all --json | jq -r '.addresses[] | select(.canSend) | .address'

• —Um início de sessão ou uma chave sem o scope para com o código de saída 4, indica o scope em falta e explica como o obter.
• —domains delete e domains delete-address pedem-lhe confirmação. Responder que não sai com o código 10 e não altera nada. Sem supervisão e sem --yes, param com o código de saída 2 antes de enviar o que quer que seja.
• —Com um início de sessão no navegador, essas duas eliminações também pedem um código de verificação, como faz a aplicação web. Sem supervisão ninguém o pode escrever, por isso o comando para com o código de saída 4. Execute primeiro openemail verify e os 60 minutos seguintes não precisam de código. A uma chave de API nunca é pedido.
• —--dry-run mostra o pedido que uma alteração enviaria, com o corpo, e sai com o código 0 sem o enviar nem lhe pedir confirmação.
• —Uma lista lê uma página: --limit aceita de 1 a 100 e o servidor envia 25 quando é omitido, e --cursor aceita o nextCursor da página anterior. --all lê todas as páginas, --max <n> para depois desse número de itens, e --ndjson, ou --all num pipe, mostra um objeto JSON por linha. Com --json, domains list e list-addresses mostram um único documento { items, hasMore, nextCursor }.
• —Uma chave ou um início de sessão limitados a determinados domínios ou endereços continuam a ver todos os domínios e endereços. Não podem acrescentar um domínio, e qualquer outra alteração precisa do domínio inteiro entre os domínios que têm, ou a chamada é recusada com 422 capability_unsupported.
• —Uma recusa sai com o código do seu estado: 4 para um 403, como domain_allowance_reached quando o plano não permite mais domínios, 5 para um 404, 6 para um 409, como domain_already_added ou domain_claimed, e 7 para um 422, como invalid_tracking_host ou workspace_limit_reached.
• —O último domínio de um espaço de trabalho não pode ser removido a partir da CLI. Isso é um 409 last_domain, porque removê-lo elimina a caixa de correio inteira, algo que a aplicação web confirma primeiro. Um domínio que contém endereços de conta reservados dá um 409 domain_holds_reserved_addresses.
• —domains create e as duas eliminações nunca são repetidas depois de uma falha de rede. Um 409 domain_already_added, ou um 404 na sua própria segunda tentativa depois de perder a resposta, significa que a primeira funcionou. verify, update, create-address e update-address são repetidos automaticamente, já que enviar um duas vezes deixa o mesmo resultado.