Saltar para a documentação
API

Atualizar um domínio

Define, volta a verificar ou remove o domínio de rastreio personalizado e o domínio de ficheiros personalizado do domínio, as duas coisas que esta API pode alterar num domínio.

PATCHapi.openemail.uk/domains/{id}

Executa a chamada real contra o seu espaço de trabalho, com a sua própria chave.

PATCH /domains/{id}

Define, volta a verificar ou remove o domínio de rastreio personalizado e o domínio de ficheiros personalizado do domínio, as duas coisas que esta API pode alterar num domínio.

O pedido

Um domínio pode ter um domínio de rastreio personalizado e um domínio de ficheiros personalizado, cada um deles um subdomínio dele à sua escolha, como links.acme.com e files.acme.com, assim que estiver verificado ou o seu registo TXT _openemail-challenge estiver publicado. Não tem de já estar a receber correio. Definir um prepara um endereço só para esse nome, indicado em target, e record é o registo CNAME que aponta o nome para ele. Assim que uma verificação passa, as ligações rastreadas e o pixel de abertura no correio novo do domínio usam https://links.acme.com/t/..., e as ligações de transferência dos ficheiros enviados a partir dele usam https://files.acme.com/f/..., em vez do host predefinido.

Parâmetros

trackingHoststring | null
O subdomínio a usar para as ligações rastreadas e para o pixel de abertura, com 512 caracteres no máximo. É aparado e passado a minúsculas, e um `https://` ou `http://` inicial, um caminho e um ponto final são removidos antes de ser verificado. Um valor novo substitui o domínio de rastreio atual, o valor atual volta a correr a verificação, `null` ou uma cadeia vazia remove-o, e omitir o campo deixa-o como está.
storageHoststring | null
O subdomínio a usar para as ligações de transferência de ficheiros, limpo da mesma forma e sujeito aos mesmos 512 caracteres. Um valor novo substitui o domínio de ficheiros atual, o valor atual volta a correr a verificação, `null` ou uma cadeia vazia remove-o, e omitir o campo deixa-o como está.

O corpo é rigoroso quanto às chaves e tolerante quanto ao número delas. Qualquer chave que não seja trackingHost ou storageHost dá um 422 unknown_parameter, e um corpo que não traga nenhuma delas é uma chamada sem efeito que responde 200 com o domínio tal como está. Ambas podem ir na mesma chamada e são aplicadas por ordem, trackingHost primeiro: um trackingHost recusado interrompe a chamada antes de storageHost ser tocado, e um storageHost recusado deixa no lugar uma alteração de trackingHost já feita. Envie-as em separado quando qualquer uma delas tiver de valer por si.

Definir um domínio de rastreio e um domínio de ficheiros

Requer domains:write. Cada host é validado, guardado e verificado na mesma chamada, pelo que a resposta já traz o resultado dessa primeira verificação. É o mesmo corpo de GET /domains/{id}.

curl
curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \  -d '{ "trackingHost": "links.acme.com", "storageHost": "files.acme.com" }'
Resposta
{  "object": "domain",  "id": "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f",  "domain": "acme.com",  "receiving": {    "verified": true,    "verifiedAt": "2026-08-14T10:02:00.000Z",    "catchAll": false,    "lastCheckedAt": "2026-08-29T06:00:00.000Z",    "error": null  },  "sending": {    "status": "verified",    "canSend": true,    "checkedAt": "2026-08-29T06:00:00.000Z",    "error": null,    "note": "Mail from this domain is signed and can be sent."  },  "tracking": {    "host": "links.acme.com",    "status": "pending",    "active": false,    "target": "oelinks3f9a1c7e2b8d4a60.edge.openemail.uk",    "record": { "type": "CNAME", "name": "links.acme.com", "value": "oelinks3f9a1c7e2b8d4a60.edge.openemail.uk" },    "checkedAt": "2026-08-29T06:05:12.000Z",    "verifiedAt": null,    "error": "links.acme.com does not resolve yet. Add a CNAME record named links.acme.com with the value oelinks3f9a1c7e2b8d4a60.edge.openemail.uk, then check again."  },  "storage": {    "host": "files.acme.com",    "status": "pending",    "active": false,    "target": "oefiles81c40d6b2f7e9a35.edge.openemail.uk",    "record": { "type": "CNAME", "name": "files.acme.com", "value": "oefiles81c40d6b2f7e9a35.edge.openemail.uk" },    "checkedAt": "2026-08-29T06:05:12.000Z",    "verifiedAt": null,    "error": "files.acme.com does not resolve yet. Add a CNAME record named files.acme.com with the value oefiles81c40d6b2f7e9a35.edge.openemail.uk, then check again."  },  "addresses": [    { "address": "[email protected]", "enabled": true }  ],  "createdAt": "2026-08-14T09:55:11.000Z"}

Publique tracking.record e storage.record no seu fornecedor de DNS como CNAME simples, com qualquer proxy desligado. A verificação resolve cada nome e depois pede a https://links.acme.com/t/v/<nonce> ou a https://files.acme.com/f/v/<nonce> uma resposta assinada pelo OpenEmail. Um redirecionamento faz a verificação falhar, e um proxy à frente do nome também pode.

Assim que o registo resolve, uma verificação pode indicar que o nome aponta para o OpenEmail e está à espera de ser ligado. Isso é a emissão do respetivo certificado HTTPS, que acontece do nosso lado, não exige nada de si e pode demorar um pouco. Quando terminar, a verificação seguinte que passe coloca status em active.

Se o endereço não pôde ser preparado durante a chamada, record é null, target é uma cadeia vazia e error indica que está a ser preparado. Fica concluído em poucos minutos sem outra chamada, por isso volte a ler o domínio com GET /domains/{id} para obter o registo.

Os dois nomes são independentes. Uma chamada que traga apenas um dos campos deixa o outro objeto exatamente como estava, pelo que configurar os ficheiros mais tarde nunca perturba um domínio de rastreio que já esteja a funcionar.

Voltar a verificar, ou remover

Envie o host que o domínio já tem para correr a verificação agora, em vez de esperar pela seguinte agendada. Quando a última verificação, agendada ou não, correu há menos de 30 segundos, a chamada devolve o estado guardado sem alterações. Envie null num campo para remover esse nome, e omita o outro campo para manter o nome que ele tem.

curl
curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \  -d '{ "trackingHost": null }'
tracking, após a remoção
{  "host": null,  "status": "none",  "active": false,  "target": "",  "record": null,  "checkedAt": null,  "verifiedAt": null,  "error": null}

As ligações em correio já enviado mantêm o host com que saíram, e isso abrange tanto a ligação de transferência de um ficheiro como uma ligação rastreada. Depois de remover ou alterar um nome, essas ligações continuam a funcionar enquanto o antigo registo CNAME se mantiver no lugar. Voltar a configurar um nome pode dar-lhe um record diferente, por isso publique aquele que a resposta indicar.

O objeto tracking

hoststring | null
O domínio de rastreio, ou null quando o domínio não tem nenhum.
status'none' | 'pending' | 'active' | 'failed'
`none` significa que não está definido nenhum domínio de rastreio. `pending` significa que há um definido e que nunca passou uma verificação. `active` significa que o correio novo o usa. `failed` significa que já passou uma verificação e que entretanto deixou de ser usado.
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.
targetstring
O endereço para o qual o registo CNAME aponta, preparado só para este domínio de rastreio. É uma cadeia vazia enquanto `host` for null, e enquanto o endereço de um host novo ainda estiver a ser preparado.
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 de um host novo ainda estiver a ser preparado.
checkedAtstring | null
Quando o host foi verificado pela última vez, em ISO-8601. Null até à primeira verificação.
verifiedAtstring | null
Quando uma verificação passou pela última vez, em ISO-8601. Null para um host que nunca passou nenhuma.
errorstring | null
O que a última verificação encontrou, em palavras sobre as quais o dono do domínio pode agir. Null quando a última verificação passou ou quando ainda nenhuma correu. Um host que falhou uma ou duas verificações continua `active` e traz aqui o motivo.

O objeto storage

O domínio de ficheiros reporta em storage, campo a campo igual a tracking. Só difere aquilo para que o nome serve: aqui active significa que as ligações de transferência dos ficheiros enviados a partir do domínio apontam para ele.

hoststring | null
O domínio de ficheiros, ou null quando o domínio não tem nenhum.
status'none' | 'pending' | 'active' | 'failed'
`none` significa que não está definido nenhum domínio de ficheiros. `pending` significa que há um definido e que nunca passou uma verificação. `active` significa que o correio novo o usa. `failed` significa que já passou uma verificação e que entretanto deixou de ser usado.
activeboolean
True exatamente quando `status` é `active`, que é quando as ligações de transferência dos ficheiros enviados a partir do domínio usam o host.
targetstring
O endereço para o qual o registo CNAME aponta, preparado só para este domínio de ficheiros. É uma cadeia vazia enquanto `host` for null, e enquanto o endereço de um host novo ainda estiver a ser preparado.
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 ficheiros, e enquanto o endereço de um host novo ainda estiver a ser preparado.
checkedAtstring | null
Quando o host foi verificado pela última vez, em ISO-8601. Null até à primeira verificação.
verifiedAtstring | null
Quando uma verificação passou pela última vez, em ISO-8601. Null para um host que nunca passou nenhuma.
errorstring | null
O que a última verificação encontrou, em palavras sobre as quais o dono do domínio pode agir. Null quando a última verificação passou ou quando ainda nenhuma correu. Um host que falhou uma ou duas verificações continua `active` e traz aqui o motivo.

Como o host é verificado

Ambos os nomes são verificados no mesmo calendário, e cada um é verificado por si.

  • Um host que ainda não passou nenhuma verificação é verificado de 2 em 2 minutos na primeira hora, de 10 em 10 minutos no primeiro dia, de hora a hora na primeira semana e de 6 em 6 horas daí em diante.
  • Um host ativo é verificado de 10 em 10 minutos, e uma verificação falhada nele é repetida ao fim de 1 minuto e depois ao fim de 2.
  • Um host ativo deixa de ser usado ao fim de três verificações falhadas seguidas, ou quando a última verificação que passou tiver mais de 2 horas. O correio novo volta então ao host predefinido, e status lê-se failed até que uma verificação volte a passar. As verificações continuam, cada vez mais espaçadas e com um intervalo máximo de uma hora.

Um domínio de rastreio serve apenas caminhos de rastreio e um domínio de ficheiros serve apenas caminhos de transferência, e cada um responde apenas por correio enviado pelo workspace que o detém.

Erros

EstadotypecodeQuando
400invalid_request_errormalformed_jsonO corpo não é JSON válido.
403permission_errorinsufficient_scopeA chave não tem domains:write.
404not_found_errorresource_not_foundNão existe nenhum domínio com esse id neste workspace.
409conflict_errordomain_not_verifiedFoi enviado um host novo enquanto receiving.verified é false e o registo TXT _openemail-challenge do domínio ainda não está publicado. param é o campo em que veio, trackingHost ou storageHost.
409conflict_errortracking_host_in_useOutro domínio já usa o host como domínio de rastreio, o host já está a ser usado como domínio de ficheiros, ou o domínio de rastreio deste domínio é gerido por outro servidor OpenEmail. param é trackingHost.
409conflict_errorstorage_host_in_useOs mesmos três casos para o domínio de ficheiros: outro domínio já usa o host como domínio de ficheiros, o host já está a ser usado como domínio de rastreio, ou o domínio de ficheiros aqui é gerido por outro servidor OpenEmail. param é storageHost.
422validation_errorinvalid_tracking_hostO host não é um nome de anfitrião válido, ou não é permitido: tem de ser um subdomínio estrito do domínio, e não pode ser o host do caminho de retorno bounce.<domain>, um nome que pertença ao OpenEmail nem um domínio configurado para receber correio. param é trackingHost.
422validation_errorinvalid_storage_hostAs mesmas regras, recusadas no domínio de ficheiros. param é storageHost.
422validation_errorunknown_parameterUma chave do corpo que não seja trackingHost nem storageHost.
422validation_errorinvalid_parameterO corpo não é um objeto JSON, ou um campo presente não é nem uma string nem null, ou ultrapassa os 512 caracteres. Um corpo que não traga nenhum dos campos não é um erro: não altera nada e volta com 200.
422validation_errorcapability_unsupportedA chave está limitada a endereços individuais em vez de a todo este domínio, e ambos os nomes aplicam-se a todos os endereços do domínio. Uma chave que tenha o domínio em domainAllowlist pode defini-los. param é domainAllowlist.