Een domein bijwerken
Stelt het eigen tracking-domein en het eigen bestandsdomein van het domein in, controleert ze opnieuw of verwijdert ze: de twee dingen aan een domein die deze API kan wijzigen.
Voert de echte aanroep uit op je workspace, met je eigen sleutel.
PATCH /domains/{id}
Stelt het eigen tracking-domein en het eigen bestandsdomein van het domein in, controleert ze opnieuw of verwijdert ze: de twee dingen aan een domein die deze API kan wijzigen.
Het verzoek
Een domein kan één eigen tracking-domein en één eigen bestandsdomein hebben, elk een subdomein ervan dat je zelf kiest, zoals links.acme.com en files.acme.com, zodra het geverifieerd is of zijn _openemail-challenge TXT-record is gepubliceerd. Het hoeft nog geen post te ontvangen. Er een instellen bereidt een adres voor dat alleen bij die naam hoort, gemeld in target, en record is het CNAME-record dat de naam daarheen wijst. Zodra een controle slaagt, gebruiken getrackte links en de open-pixel in nieuwe post vanaf het domein https://links.acme.com/t/..., en gebruiken de downloadlinks voor bestanden die ervandaan zijn verstuurd https://files.acme.com/f/..., in plaats van de standaardhost.
Parameters
trackingHoststring | null- Het subdomein dat voor getrackte links en de open-pixel wordt gebruikt, maximaal 512 tekens. Het wordt getrimd en omgezet naar kleine letters, en een voorafgaande `https://` of `http://`, een pad en een punt aan het eind worden verwijderd voordat het wordt gecontroleerd. Een nieuwe waarde vervangt het huidige tracking-domein, de huidige waarde voert de controle opnieuw uit, `null` of een lege string verwijdert het, en het veld weglaten laat het met rust.
storageHoststring | null- Het subdomein dat voor downloadlinks van bestanden wordt gebruikt, op dezelfde manier opgeschoond en aan dezelfde 512 tekens gehouden. Een nieuwe waarde vervangt het huidige bestandsdomein, de huidige waarde voert de controle opnieuw uit, `null` of een lege string verwijdert het, en het veld weglaten laat het met rust.
De body is streng over veldnamen en soepel over hoeveel je er stuurt. Elke veldnaam anders dan trackingHost en storageHost levert een 422 unknown_parameter op, en een body met geen van beide is een no-op die 200 antwoordt met het domein zoals het is. Beide kunnen in één aanroep mee, en ze worden op volgorde toegepast, trackingHost eerst: een geweigerde trackingHost stopt de aanroep voordat storageHost wordt aangeraakt, en een geweigerde storageHost laat een al doorgevoerde wijziging van trackingHost staan. Stuur ze apart wanneer een van beide op zichzelf moet kunnen staan.
Een tracking-domein en een bestandsdomein instellen
Vereist domains:write. Elke host wordt in dezelfde aanroep gevalideerd, opgeslagen en gecontroleerd, dus het antwoord bevat al het resultaat van die eerste controle. Het is dezelfde body als bij 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"}Publiceer tracking.record en storage.record bij je DNS-provider als gewone CNAME's, met proxying uit. De controle resolvet elke naam en vraagt dan aan https://links.acme.com/t/v/<nonce> of https://files.acme.com/f/v/<nonce> om een antwoord dat door OpenEmail is ondertekend. Een redirect laat de controle mislukken, en een proxy vóór de naam kan dat ook.
Zodra het record resolvet, kan een controle melden dat de naam naar OpenEmail wijst en wacht om te worden ingeschakeld. Dat is het uitgeven van zijn HTTPS-certificaat, wat aan onze kant gebeurt, niets van jou vraagt en even kan duren. Zodra dat klaar is, zet de eerstvolgende geslaagde controle status op active.
Als het adres tijdens de aanroep niet kon worden voorbereid, is record null, is target een lege string en zegt error dat het wordt voorbereid. Het is binnen een paar minuten klaar zonder nog een aanroep, dus lees het domein opnieuw met GET /domains/{id} om het record te krijgen.
De twee namen staan los van elkaar. Een aanroep met één veld laat het andere object precies zoals het was, dus later bestanden instellen verstoort nooit een tracking-domein dat al live is.
Opnieuw controleren of verwijderen
Stuur de host die het domein al heeft om de controle nu uit te voeren in plaats van te wachten op de volgende geplande. Als de laatste controle, gepland of niet, minder dan 30 seconden geleden liep, geeft de aanroep de opgeslagen toestand ongewijzigd terug. Stuur null in een veld om die naam te verwijderen, en laat het andere veld weg om de naam die daar staat te behouden.
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}Links in al verzonden post houden de host waarmee ze de deur uit gingen, en dat geldt net zo goed voor de downloadlink op een bestand als voor een getrackte link. Nadat je een naam verwijdert of wijzigt, blijven die links werken zolang het oude CNAME-record blijft staan. Een naam opnieuw instellen kan hem een ander record geven, dus publiceer het record dat het antwoord meldt.
Het tracking-object
hoststring | null- Het tracking-domein, of null wanneer het domein er geen heeft.
status'none' | 'pending' | 'active' | 'failed'- `none` betekent dat er geen tracking-domein is ingesteld. `pending` betekent dat er een is ingesteld die nog nooit een controle heeft doorstaan. `active` betekent dat nieuwe post hem gebruikt. `failed` betekent dat hij eerder een controle doorstond en sindsdien uit gebruik is geraakt.
activeboolean- True precies wanneer `status` `active` is, en dat is wanneer getrackte links en de open-pixel in nieuwe post vanaf het domein de host gebruiken.
targetstring- Het adres waar het CNAME-record naar wijst, uitsluitend voor dit tracking-domein voorbereid. Het is een lege string zolang `host` null is, en zolang het adres voor een nieuwe host nog wordt voorbereid.
record{ type: 'CNAME'; name: string; value: string } | null- Het te publiceren record, genoemd naar `host` met `target` als waarde. Null wanneer er geen tracking-domein is, en zolang het adres voor een nieuwe host nog wordt voorbereid.
checkedAtstring | null- Wanneer de host voor het laatst is gecontroleerd, ISO-8601. Null tot de eerste controle.
verifiedAtstring | null- Wanneer een controle voor het laatst slaagde, ISO-8601. Null voor een host die er nooit een heeft doorstaan.
errorstring | null- Wat de laatste controle aantrof, in woorden waar de domeineigenaar iets mee kan. Null wanneer de laatste controle slaagde of er nog geen heeft gelopen. Een host die één of twee controles niet heeft doorstaan is nog steeds `active` en draagt de reden hier.
Het storage-object
Het bestandsdomein rapporteert in storage, veld voor veld hetzelfde als tracking. Alleen waar de naam voor wordt gebruikt verschilt: active betekent daar dat de downloadlinks voor bestanden die vanaf het domein zijn verstuurd ernaar wijzen.
hoststring | null- Het bestandsdomein, of null wanneer het domein er geen heeft.
status'none' | 'pending' | 'active' | 'failed'- `none` betekent dat er geen bestandsdomein is ingesteld. `pending` betekent dat er een is ingesteld die nog nooit een controle heeft doorstaan. `active` betekent dat nieuwe post hem gebruikt. `failed` betekent dat hij eerder een controle doorstond en sindsdien uit gebruik is geraakt.
activeboolean- True precies wanneer `status` `active` is, en dat is wanneer de downloadlinks voor bestanden die vanaf het domein zijn verstuurd de host gebruiken.
targetstring- Het adres waar het CNAME-record naar wijst, uitsluitend voor dit bestandsdomein voorbereid. Het is een lege string zolang `host` null is, en zolang het adres voor een nieuwe host nog wordt voorbereid.
record{ type: 'CNAME'; name: string; value: string } | null- Het te publiceren record, genoemd naar `host` met `target` als waarde. Null wanneer er geen bestandsdomein is, en zolang het adres voor een nieuwe host nog wordt voorbereid.
checkedAtstring | null- Wanneer de host voor het laatst is gecontroleerd, ISO-8601. Null tot de eerste controle.
verifiedAtstring | null- Wanneer een controle voor het laatst slaagde, ISO-8601. Null voor een host die er nooit een heeft doorstaan.
errorstring | null- Wat de laatste controle aantrof, in woorden waar de domeineigenaar iets mee kan. Null wanneer de laatste controle slaagde of er nog geen heeft gelopen. Een host die één of twee controles niet heeft doorstaan is nog steeds `active` en draagt de reden hier.
Hoe de host wordt gecontroleerd
Beide namen worden volgens hetzelfde schema gecontroleerd, en elk wordt afzonderlijk gecontroleerd.
- Een host die nog geen controle heeft doorstaan wordt in het eerste uur elke 2 minuten gecontroleerd, op de eerste dag elke 10 minuten, in de eerste week elk uur en daarna elke 6 uur.
- Een actieve host wordt elke 10 minuten gecontroleerd, en een mislukte controle erop wordt na 1 minuut opnieuw geprobeerd en daarna na 2.
- Een actieve host wordt niet meer gebruikt na drie mislukte controles op rij, of zodra zijn laatste geslaagde controle meer dan 2 uur oud is. Nieuwe post gaat dan terug naar de standaardhost, en
statusleestfailedtot een controle weer slaagt. De controles gaan door, telkens met een langere tussenpoos, tot hoogstens een uur.
Een tracking-domein bedient alleen tracking-paden en een bestandsdomein bedient alleen downloadpaden, en elk antwoordt alleen voor post die is verzonden door de workspace die het bezit.
Fouten
| Status | type | code | Wanneer |
|---|---|---|---|
| 400 | invalid_request_error | malformed_json | De body is geen geldige JSON. |
| 403 | permission_error | insufficient_scope | De sleutel heeft domains:write niet. |
| 404 | not_found_error | resource_not_found | Geen domein met die id in deze workspace. |
| 409 | conflict_error | domain_not_verified | Er is een nieuwe host gestuurd terwijl receiving.verified false is en het _openemail-challenge TXT-record van het domein nog niet is gepubliceerd. param is het veld waarop hij binnenkwam, trackingHost of storageHost. |
| 409 | conflict_error | tracking_host_in_use | Een ander domein gebruikt de host al als tracking-domein, de host is al in gebruik als bestandsdomein, of het tracking-domein van het domein wordt beheerd door een andere OpenEmail-server. param is trackingHost. |
| 409 | conflict_error | storage_host_in_use | Dezelfde drie gevallen voor het bestandsdomein: een ander domein gebruikt de host al als bestandsdomein, de host is al in gebruik als tracking-domein, of het bestandsdomein hier wordt beheerd door een andere OpenEmail-server. param is storageHost. |
| 422 | validation_error | invalid_tracking_host | De host is geen geldige hostnaam, of is niet toegestaan: hij moet een strikt subdomein van het domein zijn en mag niet de return-path-host bounce.<domain> zijn, geen naam die van OpenEmail is en geen domein dat is ingericht om post te ontvangen. param is trackingHost. |
| 422 | validation_error | invalid_storage_host | Dezelfde regels, geweigerd op het bestandsdomein. param is storageHost. |
| 422 | validation_error | unknown_parameter | Een andere veldnaam in de body dan trackingHost en storageHost. |
| 422 | validation_error | invalid_parameter | De body is geen JSON-object, of een veld dat aanwezig is, is noch een string noch null, of loopt over de 512 tekens heen. Een body met geen van beide velden is geen fout: er verandert niets en hij komt terug met 200. |
| 422 | validation_error | capability_unsupported | De sleutel is ingeperkt tot losse adressen in plaats van tot dit hele domein, en beide namen gelden voor elk adres op het domein. Een sleutel die het domein in domainAllowlist heeft, mag ze instellen. param is domainAllowlist. |