SDK

Domains

`domains.list`, `get` und `update`.

Alle Methoden

usage.ts

const domains = await openemail.domains.list()const domain = await openemail.domains.get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f') console.log(domain.receiving.verified, domain.sending.status)for (const address of domain.addresses) console.log(address.address, address.enabled) const updated = await openemail.domains.update(domain.id, { trackingHost: 'links.acme.com' })console.log(updated.tracking.status, updated.tracking.record?.name, updated.tracking.record?.value) await openemail.domains.update(domain.id, { trackingHost: null })

Empfangen und Senden sind zwei voneinander unabhängige Sachverhalte und werden als zwei Objekte zurückgegeben. receiving.verified bedeutet, dass der MX der Domain ihre Mail hierher bringt und ihr Eigentumsnachweis veröffentlicht ist. sending meldet die Signaturprüfung für ausgehende Mail: status ist verified, pending, failed, no_identity oder unknown, und canSend sagt, ob ein Versand von der Domain gerade jetzt angenommen würde. Ein negatives Urteil, das älter als ein Tag ist, gilt als unbekannt und nicht als Ablehnung, verzweigen Sie daher über canSend und nicht über status.

update setzt, prüft erneut oder entfernt die eigene Tracking-Domain der Domain, eine Subdomain wie links.acme.com, und löst zu derselben DomainDetailResource auf wie get. tracking meldet sie bei jedem Lesezugriff. Solange keine Prüfung bestanden ist, ist tracking.status pending, und getrackte Links sowie das Öffnungs-Pixel verwenden weiterhin den Standard-Host von OpenEmail. Sobald eine Prüfung besteht, ist er active und neue Mail von der Domain nutzt für beides die Tracking-Domain.

get listet außerdem die Adressen der Domain auf. addresses.list() ist der verwandte Aufruf: jede Adresse, die DIESER SCHLÜSSEL in einen From-Header setzen darf, was enger gefasst ist.

Parameter: domains.get

domainIdstringerforderlich: Die id aus `domains.list`, eine UUID, die beim Hinzufügen der Domain erzeugt wurde, nicht der Hostname, `get('example.com')` findet daher nichts. Die Suche ist außer auf die id auch auf die eigene connection des Schlüssels eingegrenzt, die Domain eines anderen Workspace ergibt daher ein 404 und kein 403.

Parameter: domains.update

idstringerforderlich: Dieselbe Domain-id, die `get` entgegennimmt. `domains:write` ist der benötigte Scope.
patch.trackingHoststring | nullerforderlich: Eine Subdomain der Domain, höchstens 512 Zeichen, etwa `links.acme.com`. Sie wird getrimmt und in Kleinbuchstaben umgewandelt, ein führendes `https://` oder `http://`, ein Pfad und ein abschließender Punkt werden entfernt. Ein neuer Wert wird im selben Aufruf validiert, gespeichert und geprüft. Der Wert, den die Domain bereits hat, startet die Prüfung erneut, außer die letzte liegt weniger als 30 Sekunden zurück. `null` oder eine leere Zeichenkette entfernt die Tracking-Domain.

Ein abgelehnter Host wirft einen OpenEmailApiError, der in param trackingHost nennt: 422 invalid_tracking_host für einen Namen, der nicht verwendet werden kann, etwa einen außerhalb der Domain, 409 domain_not_verified für einen neuen Host, solange receiving.verified false ist und der TXT-Eintrag _openemail-challenge der Domain noch nicht veröffentlicht ist, und 409 tracking_host_in_use für einen Namen, den eine andere Domain bereits nutzt, oder wenn die Tracking-Domain von einem anderen OpenEmail-Server verwaltet wird. Ein auf bestimmte Adressen beschränkter Schlüssel erhält 422 capability_unsupported, weil eine Tracking-Domain für jede Adresse der Domain gilt.

Antwort: DomainDetailResource

object'domain': Immer der String `domain`, auf `list`-Zeilen ebenso wie auf dieser.
idstring: Die UUID der Domain. Stabil über die Lebensdauer der Zeile und das einzige Handle, das die übrigen Domain-Aufrufe akzeptieren.
domainstring: Der blanke Hostname, in Kleinbuchstaben: `example.com`. Produktweit eindeutig, ein Inhaber pro Domain, zwei Workspaces können sie daher nicht beide beanspruchen.
receiving.verifiedboolean: True, sobald DNS den MX der Domain gezeigt hat, der einen Host nennt, der ihre Mail hierher bringt, und, sofern die Zeile ein Challenge-Token trägt, den passenden TXT-Eintrag `_openemail-challenge`. Der MX allein beweist nichts, da jede Domain, für die wir empfangen, dieselben Hostnamen veröffentlicht; darum gibt es das Token, und darum ist dieses Flag die Schranke, die die eingehende Zustellung vor der Annahme von Mail prüft.
receiving.verifiedAtstring | null: Wann die Verifizierung bestanden wurde, ISO-8601. Null, solange das nicht der Fall ist, und `verified` wird genau aus dieser Spalte abgeleitet, beide können sich daher nie widersprechen.
receiving.catchAllboolean: Ob jeder local-part angenommen wird. Standardmäßig an für Domains, die seit Einführung dieser Regel hinzugefügt wurden; ist es aus, werden nur auf der Domain benannte Adressen angenommen und der Rest bereits zur SMTP-Zeit abgewiesen, der Absender erhält also einen Bounce statt Schweigen.
receiving.lastCheckedAtstring | null: Wann DNS zuletzt zu dieser Domain befragt wurde. Null heißt nie nachgesehen, was sich für jemanden, der vor einer Minute eine Domain hinzugefügt hat, sehr anders liest als ein Fehlschlag. Dieser Endpunkt meldet das gespeicherte Ergebnis und führt nie eine eigene Prüfung durch.
receiving.errorstring | null: Warum die letzte Prüfung nicht bestanden wurde, in Worten, auf die der Inhaber reagieren kann: `No MX records yet. DNS changes can take a few minutes to spread.` ist ein typisches Beispiel. Null, sobald sie besteht, und gespeichert statt abgeleitet, damit ein Neuladen und die geplante erneute Prüfung dasselbe sagen.
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown': Der Signaturstatus für ausgehende Mail, wie ihn die letzte Prüfung gesehen hat. Aus der gespeicherten Prüfung gelesen und nicht bei dieser Anfrage neu ermittelt, `sending.checkedAt` sagt daher, wie alt er ist.
sending.canSendboolean: Ob ein Versand von dieser Domain gerade jetzt angenommen würde. Ein negatives Urteil, das älter als ein Tag ist, gilt als unbekannt und nicht als Ablehnung, dieser Wert kann daher true sein, während `status` `pending` ist. Verzweigen Sie vor einem Versand hierüber: Ist er false, wird `emails.send` von dieser Domain mit einem 409 `domain_not_sendable` abgelehnt.
sending.checkedAtstring | null: Wann der Signaturstatus zuletzt geprüft wurde, ISO-8601. Null heißt nie, was sich sehr anders liest als ein Fehlschlag.
sending.errorstring | null: Der letzte Signaturfehler in Worten, oder null, sobald die Prüfung besteht.
sending.notestring: Einer von fünf Sätzen, ausgewählt nach `sending.status`, der in Worten erklärt, was dieser Zustand bedeutet und worauf ein Domain-Inhaber reagieren kann. Fließtext für Menschen. Verzweigen Sie über `sending.canSend` statt hierüber.
trackingDomainTracking: Die eigene Tracking-Domain der Domain, auf `list`-Zeilen ebenso wie auf dieser, und das, was `update` ändert.
tracking.hoststring | null: Die Tracking-Domain, etwa `links.acme.com`, oder null, wenn keine gesetzt ist.
tracking.status'none' | 'pending' | 'active' | 'failed': `none` bedeutet, dass keine Tracking-Domain gesetzt ist, `pending`, dass sie nie eine Prüfung bestanden hat, `active`, dass neue Mail sie verwendet, und `failed`, dass sie zuvor bestanden hat und seitdem aus dem Einsatz gefallen ist. Ein aktiver Host fällt nach drei fehlgeschlagenen Prüfungen in Folge heraus oder sobald seine letzte bestandene Prüfung mehr als 2 Stunden zurückliegt.
tracking.activeboolean: Genau dann true, wenn `status` `active` ist, also wenn getrackte Links und das Öffnungs-Pixel in neuer Mail von der Domain den Host verwenden.
tracking.targetstring: Die Adresse, auf die der CNAME-Eintrag zeigt, allein für diese Tracking-Domain vorbereitet. Eine leere Zeichenkette, solange `host` null ist und solange die Adresse für einen neuen Host noch vorbereitet wird.
tracking.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.
tracking.checkedAtstring | null: Wann der Host zuletzt geprüft wurde, ISO-8601. Null bis zur ersten Prüfung.
tracking.verifiedAtstring | null: Wann zuletzt eine Prüfung bestanden wurde, ISO-8601. Null bei einem Host, der nie eine bestanden hat.
tracking.errorstring | null: Was die letzte Prüfung ergeben hat, in Worten, auf die der Domain-Inhaber reagieren 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.
addressesArray<{ address: string; enabled: boolean }>: Jede Adresszeile der Domain, also das, was `get` gegenüber einer `list`-Zeile ergänzt. Enthalten sind auch die Zeilen, die die Zustellung unter catch-all selbst geschrieben hat, und diese werden in dem Moment nicht mehr angenommen, in dem catch-all abgeschaltet wird; das array ist also keine Liste dessen, was empfangen wird.
addresses[].addressstring: Die vollständige Adresse, aus dem gespeicherten local-part und dem Hostnamen neu zusammengesetzt und in Kleinbuchstaben, sie passt daher immer zur `domain` oben, statt von ihr abzuweichen.
addresses[].enabledboolean: False deaktiviert die Adresse, und eine deaktivierte wird auch dann abgewiesen, wenn catch-all an ist. Jede Zeile wird in beiden Fällen aufgeführt, filtern Sie daher hierüber, statt das array als die Menge der funktionierenden Adressen zu lesen.
createdAtstring: Wann die Domain-Zeile hinzugefügt wurde, ISO-8601. Nicht, wann sie verifiziert wurde: Das ist `receiving.verifiedAt`, das null sein kann, während dieser Wert gesetzt ist.