Domains
`domains->list`, `listAll`, `iterate`, `get` und `update`.
Jede Methode
$page = $client->domains->list(); foreach ($page as $row) { echo $row['domain'], ' ', $row['sending']['canSend'] ? 'can send' : 'cannot send yet', PHP_EOL;} $domain = $client->domains->get('b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f');echo $domain['receiving']['verified'] ? 'receiving' : 'not verified yet', ' ', $domain['sending']['status'], PHP_EOL; foreach ($domain['addresses'] as $entry) { echo $entry['address'], ' ', $entry['enabled'] ? 'on' : 'off', PHP_EOL;}Empfangen und Senden sind zwei voneinander unabhängige Sachverhalte und werden als zwei Arrays 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, gelesen als $domain['sending']['canSend'], und nicht über status.
list gibt eine OpenEmail\Result\Page mit Domains in alphabetischer Reihenfolge zurück, und listAll gibt sie alle in einem einzigen Array zurück. iterate gibt einen Generator zurück, der sie einzeln liefert.
$domainId = 'b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f'; $updated = $client->domains->update($domainId, ['trackingHost' => 'links.acme.com']);$record = $updated['tracking']['record'];echo $updated['tracking']['status'], ' ', $record['name'] ?? '', ' ', $record['value'] ?? '', PHP_EOL; $client->domains->update($domainId, ['trackingHost' => null]);update setzt, prüft erneut oder entfernt die eigene Tracking-Domain der Domain, eine Subdomain wie links.acme.com, und gibt dasselbe Array wie get zurück. 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 auch die Adressen auf der Domain. addresses->list ist der verwandte Aufruf: die Adressen, die dieser Schlüssel in einen From-Header setzen darf, was enger gefasst ist, jeweils mit einem Urteil canSend. Es gibt eine OpenEmail\Result\AddressBookPage zurück, die sie in addresses statt in items hält, neben domains und unrestricted. Sein listAll gibt ein OpenEmail\Result\AddressBook zurück.
appHost ist ein eigener Namespace, $client->appHost. get, set, verify und delete lesen und ändern die Web-App-Adresse des Workspace, eine Subdomain wie mailbox.acme.com auf einer dieser Domains oder jeder anderen Domain, die der Workspace kontrolliert, wo sich seine Leute unter der Marke des Workspace anmelden. set gibt die zu veröffentlichenden DNS-Einträge zurück, in record und, bei einer Domain außerhalb des Workspace, in ownershipRecord. delete und ein set, das eine Adresse ersetzt, verlangen von einer OAuth-App einen Bestätigungscode: Solange sie keinen hat, wirft der Aufruf einen 403, dessen isStepUpRequired() true ist.
branding legt diese Marke fest. branding->get liest die Links zu Zeichen, Logo, Logo für den Dunkelmodus und Anmeldebild, die zwei Schriften und den Anmeldehintergrund. branding->update ändert die Schriften und den Hintergrund, branding->uploadImage($variant, $data, contentType: ...) lädt eines der vier Bilder hoch, und branding->removeImage($variant) entfernt eines. Die Variante ist mark, wordmark, wordmark-dark oder login-background, und OpenEmail\Constants\BrandImageVariants nennt sie. Die Daten sind ein String aus Bytes, eine Stream-Ressource, eine SplFileInfo oder ein PSR-7-Stream oder eine hochgeladene Datei. Eine SplFileInfo wie new \SplFileInfo('logo.svg'), ein auf einer Datei geöffneter Stream oder ein Laravel- oder Symfony-Upload bringt seinen Typ mit. Andere Bytes brauchen contentType:, und ein Bild ohne Typ wird mit einem 422 invalid_image abgelehnt. Das Logo ist das, was die Web-App-Adresse und, mit einem kostenpflichtigen Tarif, die für den Workspace gesendeten E-Mails mit der Marke versieht.
Parameter: domains->get
idstringerforderlich- 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 den eigenen Workspace des Schlüssels eingegrenzt, die Domain eines anderen Workspace ergibt daher einen 404, geworfen als `NotFoundException`, und keinen 403. Eine leere id wirft eine `InvalidArgumentException`, bevor etwas gesendet wird.
Parameter: domains->update
idstringerforderlich- Dieselbe Domain-id, die `get` entgegennimmt. `domains:write` ist der benötigte Scope.
trackingHoststring or null- Eine Subdomain der Domain, höchstens 512 Zeichen, etwa `links.acme.com`. Sie wird getrimmt und in Kleinbuchstaben umgewandelt, und 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. Übergeben Sie null oder einen leeren String, um die Tracking-Domain zu entfernen, und lassen Sie den Schlüssel weg, um sie unverändert zu lassen.
Ein abgelehnter Host wirft eine ApiException, die in param trackingHost nennt: einen 422 invalid_tracking_host für einen Namen, der nicht verwendet werden kann, etwa einen außerhalb der Domain, einen 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 einen 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. Der 422 kommt als ValidationException an und jeder 409 als ConflictException. Ein auf bestimmte Adressen beschränkter Schlüssel bekommt einen 422 capability_unsupported, weil eine Tracking-Domain für jede Adresse auf der Domain gilt.
Der Patch ist ein einzelnes Array mit den camelCase-Namen der API als Schlüsseln. Ein Schlüssel wie tracking_host wird daher so gesendet, wie er geschrieben ist, und mit einem 422 unknown_parameter abgelehnt. update nimmt außerdem catchAll, storageHost für eine Dateien-Domain wie files.acme.com und dmarcPolicy. Jeder Schlüssel ist optional, und die Methodenreferenz behandelt jeden einzelnen. Der Client wiederholt update wie einen Lesevorgang, weil eine Wiederholung den Host bereits gesetzt vorfindet und ihn höchstens erneut prüft.
Antwort: eine Domain (domains->get)
objectstring- 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.verifiedbool- 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 or null- Wann die Verifizierung bestanden wurde, als String nach 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.catchAllbool- 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 or null- Wann DNS zuletzt zu dieser Domain befragt wurde. null, wenn DNS nie befragt wurde, was sich für jemanden, der vor einer Minute eine Domain hinzugefügt hat, sehr anders liest als ein Fehlschlag. Das Lesen einer unverifizierten Domain fragt DNS erneut, sobald die letzte Prüfung älter als 20 Sekunden ist. Wiederholtes Abfragen von `get` ist also eine Möglichkeit, auf die Verifizierung zu warten, und `verify` prüft sofort.
receiving.errorstring or 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 die Prüfung besteht, und gespeichert statt abgeleitet, damit ein Neuladen und die geplante erneute Prüfung dasselbe sagen.
sending.statusstring- Der Signaturstatus für ausgehende Mail, wie ihn die letzte Prüfung gesehen hat: `verified`, `pending`, `failed`, `no_identity` oder `unknown`. Er wird aus der gespeicherten Prüfung gelesen, `sending.checkedAt` sagt daher, wie alt er ist.
sending.canSendbool- 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 or null- Wann der Signaturstatus zuletzt geprüft wurde, als String nach ISO 8601. null, wenn er nie geprüft wurde, was sich sehr anders liest als ein Fehlschlag.
sending.errorstring or 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. Es ist Fließtext für Menschen, verzweigen Sie also über `sending.canSend` statt hierüber.
trackingarray- Die eigene Tracking-Domain der Domain, auf `list`-Zeilen ebenso wie auf dieser, und das, was `update` ändert.
tracking.hoststring or null- Die Tracking-Domain, etwa `links.acme.com`, oder null, wenn keine gesetzt ist.
tracking.statusstring- `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.activebool- 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.
tracking.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.
tracking.recordarray or null- Der zu veröffentlichende Eintrag, ein Array mit `type` (immer `CNAME`), `name` und `value`, 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. `$domain['tracking']['record']['value'] ?? null` liest ihn daher gefahrlos.
tracking.checkedAtstring or null- Wann der Host zuletzt geprüft wurde, als String nach ISO 8601. null bis zur ersten Prüfung.
tracking.verifiedAtstring or null- Wann zuletzt eine Prüfung bestanden wurde, als String nach ISO 8601. null bei einem Host, der noch nie eine bestanden hat.
tracking.errorstring or null- Was die letzte Prüfung ergeben hat, in Worten, mit denen der Domain-Inhaber 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.
addressesarray- 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. Die Liste ist also keine Aufstellung 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[].enabledbool- 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 die Liste als die Menge der funktionierenden Adressen zu lesen.
createdAtstring- Wann die Domain-Zeile hinzugefügt wurde, als String nach ISO 8601. Nicht, wann die Domain verifiziert wurde: Das ist `receiving.verifiedAt`, das null sein kann, während dieser Wert gesetzt ist.