API

Eine Domain aktualisieren

Setzt, prüft erneut oder entfernt die eigene Tracking-Domain und die eigene Dateien-Domain einer Domain, die beiden Dinge an einer Domain, die diese API ändern kann.

PATCHapi.openemail.uk/domains/{id}

Führt den echten Aufruf gegen Ihren Workspace aus, mit Ihrem eigenen Schlüssel.

PATCH /domains/{id}

Setzt, prüft erneut oder entfernt die eigene Tracking-Domain und die eigene Dateien-Domain einer Domain, die beiden Dinge an einer Domain, die diese API ändern kann.

Die Anfrage

Eine Domain kann eine eigene Tracking-Domain und eine eigene Dateien-Domain haben, jeweils eine von Ihnen gewählte Subdomain von ihr, etwa links.acme.com und files.acme.com, sobald sie verifiziert ist oder ihr _openemail-challenge TXT-Eintrag veröffentlicht ist. Sie muss noch keine Mail empfangen. Beim Setzen wird eine Adresse allein für diesen Namen vorbereitet, gemeldet in target, und record ist der CNAME-Eintrag, der den Namen darauf zeigen lässt. Sobald eine Prüfung besteht, verwenden getrackte Links und das Open-Pixel in neuer Mail von der Domain https://links.acme.com/t/..., und die Download-Links für von ihr versendete Dateien verwenden https://files.acme.com/f/... statt des Standard-Hosts.

Parameter

trackingHoststring | null: Die Subdomain, die für getrackte Links und das Open-Pixel verwendet wird, höchstens 512 Zeichen. Sie wird getrimmt und in Kleinbuchstaben umgewandelt; ein führendes `https://` oder `http://`, ein Pfad und ein abschließender Punkt werden vor der Prüfung entfernt. Ein neuer Wert ersetzt die aktuelle Tracking-Domain, der aktuelle Wert startet die Prüfung erneut, `null` oder eine leere Zeichenkette entfernt sie, und wird das Feld weggelassen, bleibt sie unberührt.
storageHoststring | null: Die Subdomain, die für Datei-Download-Links verwendet wird, auf dieselbe Weise bereinigt und an dieselben 512 Zeichen gebunden. Ein neuer Wert ersetzt die aktuelle Dateien-Domain, der aktuelle Wert startet die Prüfung erneut, `null` oder eine leere Zeichenkette entfernt sie, und wird das Feld weggelassen, bleibt sie unberührt.

Der Body ist streng bei den Schlüsseln und großzügig bei ihrer Anzahl. Jeder Schlüssel außer trackingHost und storageHost ergibt ein 422 unknown_parameter, und ein Body, der keinen von beiden enthält, ist ein No-op und antwortet mit 200 und der Domain im aktuellen Stand. Beide können in einem Aufruf stehen und werden der Reihe nach angewendet, trackingHost zuerst: Ein abgelehnter trackingHost beendet den Aufruf, bevor storageHost angefasst wird, und ein abgelehnter storageHost lässt eine bereits vorgenommene Änderung an trackingHost bestehen. Senden Sie beide getrennt, wenn eines von beiden für sich allein gelten muss.

Eine Tracking-Domain und eine Dateien-Domain einrichten

Erfordert domains:write. Jeder Host wird im selben Aufruf validiert, gespeichert und geprüft; die Antwort trägt daher bereits das Ergebnis dieser ersten Prüfung. Es ist derselbe Body wie bei 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" }'

Antwort

{  "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"}

Veröffentlichen Sie tracking.record und storage.record bei Ihrem DNS-Anbieter als einfache CNAMEs, mit abgeschaltetem Proxying. Die Prüfung löst jeden Namen auf und fragt dann https://links.acme.com/t/v/<nonce> oder https://files.acme.com/f/v/<nonce> nach einer von OpenEmail signierten Antwort. Eine Weiterleitung lässt die Prüfung scheitern, und ein Proxy vor dem Namen kann das ebenfalls.

Sobald der Eintrag auflöst, kann eine Prüfung melden, dass der Name auf OpenEmail zeigt und auf die Freischaltung wartet. Dahinter steht die Ausstellung seines HTTPS-Zertifikats; das geschieht auf unserer Seite, erfordert nichts von Ihnen und kann etwas dauern. Ist sie abgeschlossen, setzt die nächste bestandene Prüfung status auf active.

Konnte die Adresse während des Aufrufs nicht vorbereitet werden, ist record null, target eine leere Zeichenkette, und error meldet, dass sie gerade vorbereitet wird. Das ist ohne weiteren Aufruf innerhalb weniger Minuten erledigt; lesen Sie die Domain für den Eintrag also erneut mit GET /domains/{id}.

Die beiden Namen sind voneinander unabhängig. Ein Aufruf mit nur einem Feld lässt das andere Objekt genau so, wie es war; die Dateien-Domain später einzurichten stört also nie eine bereits aktive Tracking-Domain.

Erneut prüfen oder entfernen

Senden Sie den Host, den die Domain bereits hat, um die Prüfung jetzt auszuführen, statt auf die nächste geplante zu warten. Lief die letzte Prüfung, geplant oder nicht, vor weniger als 30 Sekunden, gibt der Aufruf den gespeicherten Zustand unverändert zurück. Senden Sie null in einem Feld, um diesen Namen zu entfernen, und lassen Sie das andere Feld weg, damit es den Namen behält, den es trägt.

curl

curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" -H "$AUTH" -H "Content-Type: application/json" \  -d '{ "trackingHost": null }'

tracking, nach dem Entfernen

{  "host": null,  "status": "none",  "active": false,  "target": "",  "record": null,  "checkedAt": null,  "verifiedAt": null,  "error": null}

Links in bereits versendeter Mail behalten den Host, mit dem sie hinausgegangen sind, und das gilt für den Download-Link einer Datei ebenso wie für einen getrackten Link. Nachdem Sie einen Namen entfernt oder geändert haben, funktionieren diese Links weiter, solange der alte CNAME-Eintrag bestehen bleibt. Wird ein Name erneut eingerichtet, kann er ein anderes record erhalten; veröffentlichen Sie daher das, was die Antwort meldet.

Das tracking-Objekt

hoststring | null: Die Tracking-Domain, oder null, wenn die Domain keine hat.
status'none' | 'pending' | 'active' | 'failed': `none` bedeutet, dass keine Tracking-Domain gesetzt ist. `pending` bedeutet, dass eine gesetzt ist und noch nie eine Prüfung bestanden hat. `active` bedeutet, dass neue Mail sie verwendet. `failed` bedeutet, dass sie zuvor eine Prüfung bestanden hat und seither nicht mehr verwendet wird.
activeboolean: Genau dann true, wenn `status` auf `active` steht, also wenn getrackte Links und das Open-Pixel in neuer Mail von der Domain den Host verwenden.
targetstring: Die Adresse, auf die der CNAME-Eintrag zeigt, allein für diese Tracking-Domain vorbereitet. Sie ist eine leere Zeichenkette, solange `host` null ist und solange die Adresse für einen neuen Host noch vorbereitet wird.
record{ type: 'CNAME'; name: string; value: string } | null: Der zu veröffentlichende Eintrag, benannt nach `host`, mit `target` als Wert. Null, wenn es keine Tracking-Domain gibt, und solange die Adresse für einen neuen Host noch vorbereitet wird.
checkedAtstring | null: Wann der Host zuletzt geprüft wurde, ISO-8601. Null bis zur ersten Prüfung.
verifiedAtstring | null: Wann zuletzt eine Prüfung bestanden wurde, ISO-8601. Null bei einem Host, der noch nie eine bestanden hat.
errorstring | null: Was die letzte Prüfung ergeben hat, in Worten, mit denen der Domaininhaber etwas anfangen kann. Null, wenn die letzte Prüfung bestanden wurde oder noch keine gelaufen ist. Ein Host, der ein oder zwei Prüfungen nicht bestanden hat, ist weiterhin `active` und trägt den Grund hier.

Das storage-Objekt

Die Dateien-Domain meldet in storage, Feld für Feld genauso wie tracking. Es unterscheidet sich nur, wofür der Name verwendet wird: active bedeutet dort, dass die Download-Links für von der Domain versendete Dateien darauf zeigen.

hoststring | null: Die Dateien-Domain, oder null, wenn die Domain keine hat.
status'none' | 'pending' | 'active' | 'failed': `none` bedeutet, dass keine Dateien-Domain gesetzt ist. `pending` bedeutet, dass eine gesetzt ist und noch nie eine Prüfung bestanden hat. `active` bedeutet, dass neue Mail sie verwendet. `failed` bedeutet, dass sie zuvor eine Prüfung bestanden hat und seither nicht mehr verwendet wird.
activeboolean: Genau dann true, wenn `status` auf `active` steht, also wenn die Download-Links für von der Domain versendete Dateien den Host verwenden.
targetstring: Die Adresse, auf die der CNAME-Eintrag zeigt, allein für diese Dateien-Domain vorbereitet. Sie ist eine leere Zeichenkette, solange `host` null ist und solange die Adresse für einen neuen Host noch vorbereitet wird.
record{ type: 'CNAME'; name: string; value: string } | null: Der zu veröffentlichende Eintrag, benannt nach `host`, mit `target` als Wert. Null, wenn es keine Dateien-Domain gibt, und solange die Adresse für einen neuen Host noch vorbereitet wird.
checkedAtstring | null: Wann der Host zuletzt geprüft wurde, ISO-8601. Null bis zur ersten Prüfung.
verifiedAtstring | null: Wann zuletzt eine Prüfung bestanden wurde, ISO-8601. Null bei einem Host, der noch nie eine bestanden hat.
errorstring | null: Was die letzte Prüfung ergeben hat, in Worten, mit denen der Domaininhaber etwas anfangen kann. Null, wenn die letzte Prüfung bestanden wurde oder noch keine gelaufen ist. Ein Host, der ein oder zwei Prüfungen nicht bestanden hat, ist weiterhin `active` und trägt den Grund hier.

Wie der Host geprüft wird

Beide Namen werden nach demselben Zeitplan geprüft, und jeder wird für sich geprüft.

Ein Host, der noch keine Prüfung bestanden hat, wird in seiner ersten Stunde alle 2 Minuten geprüft, an seinem ersten Tag alle 10 Minuten, in seiner ersten Woche stündlich und danach alle 6 Stunden.
Ein aktiver Host wird alle 10 Minuten geprüft, und eine fehlgeschlagene Prüfung wird nach 1 Minute und dann nach 2 Minuten wiederholt.
Ein aktiver Host wird nach drei fehlgeschlagenen Prüfungen in Folge nicht mehr verwendet, ebenso wenn seine letzte bestandene Prüfung mehr als 2 Stunden zurückliegt. Neue Mail fällt dann auf den Standard-Host zurück, und status steht auf failed, bis wieder eine Prüfung besteht. Die Prüfungen laufen weiter, jedes Mal in größeren Abständen und höchstens eine Stunde auseinander.

Eine Tracking-Domain bedient nur Tracking-Pfade und eine Dateien-Domain nur Download-Pfade, und jede antwortet nur für Mail, die der Workspace versendet hat, dem sie gehört.

Fehler

Status	type	code	Wann
400	invalid_request_error	malformed_json	Der Body ist kein gültiges JSON.
403	permission_error	insufficient_scope	Der Schlüssel besitzt `domains:write` nicht.
404	not_found_error	resource_not_found	Keine Domain mit dieser id in diesem Workspace.
409	conflict_error	domain_not_verified	Ein neuer Host wurde gesendet, während `receiving.verified` false ist und der `_openemail-challenge` TXT-Eintrag der Domain noch nicht veröffentlicht ist. `param` ist das Feld, in dem er kam, `trackingHost` oder `storageHost`.
409	conflict_error	tracking_host_in_use	Eine andere Domain verwendet den Host bereits als ihre Tracking-Domain, der Host wird bereits als Dateien-Domain verwendet, oder die Tracking-Domain der Domain wird von einem anderen OpenEmail-Server verwaltet. `param` ist `trackingHost`.
409	conflict_error	storage_host_in_use	Dieselben drei Fälle für die Dateien-Domain: Eine andere Domain verwendet den Host bereits als ihre Dateien-Domain, der Host wird bereits als Tracking-Domain verwendet, oder die Dateien-Domain hier wird von einem anderen OpenEmail-Server verwaltet. `param` ist `storageHost`.
422	validation_error	invalid_tracking_host	Der Host ist kein gültiger Hostname oder nicht zulässig: Er muss eine echte Subdomain der Domain sein und darf weder der Return-Path-Host `bounce.<domain>` noch ein Name, der OpenEmail gehört, noch eine auf Mailempfang eingerichtete Domain sein. `param` ist `trackingHost`.
422	validation_error	invalid_storage_host	Dieselben Regeln, abgelehnt bei der Dateien-Domain. `param` ist `storageHost`.
422	validation_error	unknown_parameter	Ein Body-Schlüssel außer `trackingHost` und `storageHost`.
422	validation_error	invalid_parameter	Der Body ist kein JSON-Objekt, oder ein vorhandenes Feld ist weder ein string noch null oder überschreitet 512 Zeichen. Ein Body ohne beide Felder ist kein Fehler: Er ändert nichts und kommt mit 200 zurück.
422	validation_error	capability_unsupported	Der Schlüssel ist auf einzelne Adressen eingeschränkt statt auf diese ganze Domain, und beide Namen gelten für jede Adresse der Domain. Ein Schlüssel, der die Domain in `domainAllowlist` führt, darf sie setzen. `param` ist `domainAllowlist`.