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.
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 -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" }'{ "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 -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "trackingHost": null }'{ "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
statuslê-sefailedaté 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
| Estado | type | code | Quando |
|---|---|---|---|
| 400 | invalid_request_error | malformed_json | O corpo não é JSON válido. |
| 403 | permission_error | insufficient_scope | A chave não tem domains:write. |
| 404 | not_found_error | resource_not_found | Não existe nenhum domínio com esse id neste workspace. |
| 409 | conflict_error | domain_not_verified | Foi 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. |
| 409 | conflict_error | tracking_host_in_use | Outro 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. |
| 409 | conflict_error | storage_host_in_use | Os 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. |
| 422 | validation_error | invalid_tracking_host | O 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. |
| 422 | validation_error | invalid_storage_host | As mesmas regras, recusadas no domínio de ficheiros. param é storageHost. |
| 422 | validation_error | unknown_parameter | Uma chave do corpo que não seja trackingHost nem storageHost. |
| 422 | validation_error | invalid_parameter | O 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. |
| 422 | validation_error | capability_unsupported | A 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. |