Domains
`domains.list`, `list_all`, `iterate`, `get` und `update`.
Jede Methode
page = client.domains.listpage.items.each { |row| puts "#{row[:domain]} #{row.dig(:sending, :canSend)}" } domain = client.domains.get("b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f")puts domain.dig(:receiving, :verified), domain.dig(:sending, :status) domain[:addresses].each do |entry| puts "#{entry[:address]} #{entry[:enabled]}"endEmpfangen und Senden sind zwei voneinander unabhängige Sachverhalte und werden als zwei Hashes 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.dig(:sending, :canSend), und nicht über status.
list gibt eine OpenEmail::Page mit Domains in alphabetischer Reihenfolge zurück, und list_all gibt sie alle in einem einzigen Array zurück. iterate übergibt sie einzeln an einen Block. Ohne Block gibt es einen Enumerator zurück.
domain_id = "b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f" updated = client.domains.update(domain_id, trackingHost: "links.acme.com")puts updated.dig(:tracking, :status), updated.dig(:tracking, :record, :name), updated.dig(:tracking, :record, :value) client.domains.update(domain_id, trackingHost: nil)update setzt, prüft erneut oder entfernt die eigene Tracking-Domain der Domain, eine Subdomain wie links.acme.com, und gibt denselben Hash 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::AddressBookPage zurück, die sie in addresses statt in items hält, neben domains und unrestricted. Sein list_all gibt ein OpenEmail::AddressBook zurück.
app_host ist ein eigener Namespace, client.app_host. 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, löst der Aufruf einen 403 aus, dessen step_up_required? true ist.
branding legt diese Marke fest. get liest die Links zu Zeichen, Logo, Logo für den Dunkelmodus und Anmeldebild, die zwei Schriften und den Anmeldehintergrund. update ändert die Schriften und den Hintergrund, upload_image(variant, data, content_type: nil) lädt eines der vier Bilder hoch, und remove_image(variant) entfernt eines. variant ist mark, wordmark, wordmark-dark oder login-background, und OpenEmail::BRAND_IMAGE_VARIANTS nennt sie. data ist ein binärer String, ein IO oder ein Pathname. Ein Pathname wie Pathname("logo.svg"), eine File oder ein Rails-Upload bringt seinen Typ mit. Andere Bytes brauchen content_type:, 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, ausgelöst als `OpenEmail::NotFoundError`, und keinen 403. Eine nil- oder leere id löst einen ArgumentError aus, bevor etwas gesendet wird.
Parameter: domains.update
idStringerforderlich- Dieselbe Domain-id, die `get` entgegennimmt. `domains:write` ist der benötigte Scope.
trackingHostString or nil- 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 nil oder einen leeren String, um die Tracking-Domain zu entfernen, und lassen Sie das Feld weg, um sie unverändert zu lassen.
Ein abgelehnter Host löst einen OpenEmail::ApiError aus, der 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 OpenEmail::ValidationError an und jeder 409 als OpenEmail::ConflictError. 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 besteht aus Keyword-Argumenten oder einem einzelnen Hash, und seine Felder behalten die camelCase-Namen der API. tracking_host: wird daher so gesendet, wie es 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. Jedes Feld ist optional, und die Methodenreferenz behandelt jedes einzelne. Das Gem 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.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 or nil- Wann die Verifizierung bestanden wurde, als String nach ISO 8601. nil, 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 or nil- Wann DNS zuletzt zu dieser Domain befragt wurde. nil, 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 nil- 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. nil, 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.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 or nil- Wann der Signaturstatus zuletzt geprüft wurde, als String nach ISO 8601. nil, wenn er nie geprüft wurde, was sich sehr anders liest als ein Fehlschlag.
sending.errorString or nil- Der letzte Signaturfehler in Worten, oder nil, 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.
trackingHash- Die eigene Tracking-Domain der Domain, auf `list`-Zeilen ebenso wie auf dieser, und das, was `update` ändert.
tracking.hostString or nil- Die Tracking-Domain, etwa `links.acme.com`, oder nil, 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.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.
tracking.targetString- Die Adresse, auf die der CNAME-Eintrag zeigt, allein für diese Tracking-Domain vorbereitet. Sie ist ein leerer String, solange `host` nil ist und solange die Adresse für einen neuen Host noch vorbereitet wird.
tracking.recordHash or nil- Der zu veröffentlichende Eintrag, ein Hash mit `type` (immer `CNAME`), `name` und `value`, benannt nach `host`, mit `target` als Wert. nil, wenn es keine Tracking-Domain gibt, und solange die Adresse für einen neuen Host noch vorbereitet wird. `dig(:tracking, :record, :value)` liest ihn daher gefahrlos.
tracking.checkedAtString or nil- Wann der Host zuletzt geprüft wurde, als String nach ISO 8601. nil bis zur ersten Prüfung.
tracking.verifiedAtString or nil- Wann zuletzt eine Prüfung bestanden wurde, als String nach ISO 8601. nil bei einem Host, der noch nie eine bestanden hat.
tracking.errorString or nil- Was die letzte Prüfung ergeben hat, in Worten, mit denen der Domain-Inhaber etwas anfangen kann. nil, 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<Hash>- 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, als String nach ISO 8601. Nicht, wann die Domain verifiziert wurde: Das ist `receiving.verifiedAt`, das nil sein kann, während dieser Wert gesetzt ist.