ドメイン
`domains->list`、`listAll`、`iterate`、`get`、`update`。
すべてのメソッド
$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;}受信と送信は独立した 2 つの事実であり、2 つの配列として返されます。receiving.verified は、そのドメインの MX がメールをここへ運び、所有権チャレンジが公開されていることを意味します。sending は送信側の署名チェックを報告します。status は verified、pending、failed、no_identity、unknown のいずれかで、canSend は今そのドメインからの送信が受け付けられるかどうかを示します。1 日より古い否定的な判定は拒否ではなく不明として扱われるので、status ではなく、$domain['sending']['canSend'] として読める canSend で分岐してください。
list はアルファベット順に並んだドメインの OpenEmail\Result\Page を 1 つ返し、listAll はすべてを 1 つの配列で返します。iterate はそれらを 1 つずつ yield する Generator を返します。
$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 は、ドメイン独自のトラッキングドメイン（links.acme.com のようなサブドメイン）を設定・再チェック・削除し、get と同じ配列を返します。tracking はすべての読み取りでその状態を報告します。チェックが通るまで tracking.status は pending で、トラッキングリンクと開封ピクセルは既定の OpenEmail ホストを使い続けます。チェックが通ると active になり、そのドメインからの新しいメールは両方にトラッキングドメインを使います。
get はドメイン上のアドレスも一覧にします。関連する呼び出しが addresses->list です：このキーが From ヘッダーに入れられるアドレスで、こちらのほうが範囲は狭く、それぞれ canSend の判定を持ちます。これは OpenEmail\Result\AddressBookPage を返し、アドレスを items ではなく addresses に、domains と unrestricted と並べて保持します。その listAll は OpenEmail\Result\AddressBook を 1 つ返します。
appHost は独立した名前空間で、$client->appHost です。get、set、verify、delete は、ワークスペースの Web アプリのアドレスを読み取り・変更します。これは、これらのドメインのいずれか、またはワークスペースが管理するほかのドメイン上にある mailbox.acme.com のようなサブドメインで、ワークスペースの人々はそこでワークスペースのブランドのもとサインインします。set は公開する DNS レコードを record に、ワークスペース外のドメインではさらに ownershipRecord に入れて返します。delete と、アドレスを置き換える set は、OAuth アプリに確認コードを求めます。確認コードを得るまで、呼び出しは isStepUpRequired() が true の 403 をスローします。
branding はそのブランドを設定します。branding->get はマーク、ロゴ、ダークモード用ロゴ、サインイン画面の写真へのリンク、2 つのフォント、サインインページの背景を読み取ります。branding->update はフォントと背景を変更し、branding->uploadImage($variant, $data, contentType: ...) は 4 つの画像のいずれかをアップロードし、branding->removeImage($variant) は 1 つを削除します。バリアントは mark、wordmark、wordmark-dark、login-background のいずれかで、OpenEmail\Constants\BrandImageVariants がそれらを定義しています。データはバイト列の文字列、ストリームリソース、SplFileInfo、または PSR-7 のストリームかアップロードされたファイルです。new \SplFileInfo('logo.svg') のような SplFileInfo、ファイルで開いたストリーム、Laravel や Symfony のアップロードは種類を持っています。それ以外のバイト列には contentType: が必要で、種類のない画像は 422 invalid_image で拒否されます。Web アプリのアドレスと、有料プランではワークスペースのために送られるメールにブランドを付けるのはロゴです。
パラメーター：domains->get
idstring必須- `domains->list` から得られる id で、ドメインが追加されたときに発行された UUID です。ホスト名ではないので `get('example.com')` では何も見つかりません。検索は id だけでなくキー自身のワークスペースにもスコープされるので、他のワークスペースのドメインは 403 ではなく 404 になり、`NotFoundException` としてスローされます。空の id は、何かが送信される前に `InvalidArgumentException` をスローします。
パラメーター：domains->update
idstring必須- `get` が受け取るのと同じドメイン id です。必要なスコープは `domains:write` です。
trackingHoststring or null- そのドメインのサブドメインで、最大 512 文字。たとえば `links.acme.com` です。前後の空白が取り除かれて小文字化され、先頭の `https://` や `http://`、パス、末尾のドットは取り除かれます。新しい値は同じ呼び出しの中で検証・保存・チェックされます。ドメインがすでに持っている値を渡すと、直前のチェックから 30 秒未満でない限り、チェックが再実行されます。null または空文字列を渡すとトラッキングドメインを削除し、キーを省略するとそのままになります。
拒否されたホストは、param に trackingHost を示す ApiException をスローします。ドメインの外の名前など使えない名前には 422 invalid_tracking_host、receiving.verified が false でドメインの _openemail-challenge TXT レコードがまだ公開されていない間の新しいホストには 409 domain_not_verified、他のドメインがすでに使っている名前や、トラッキングドメインが別の OpenEmail サーバーで管理されている場合には 409 tracking_host_in_use です。422 は ValidationException として、各 409 は ConflictException として届きます。特定のアドレスに限定されたキーは 422 capability_unsupported を受け取ります。トラッキングドメインはドメイン上のすべてのアドレスに適用されるからです。
変更内容は API の camelCase の名前をキーとする 1 つの配列です。そのため tracking_host のようなキーは書かれたとおりに送られ、422 unknown_parameter で拒否されます。update は catchAll、files.acme.com のようなファイル用ドメインを指定する storageHost、dmarcPolicy も受け取ります。どのキーも省略可能で、メソッドリファレンスでそれぞれを説明しています。繰り返してもホストはすでに設定されていて、せいぜい再チェックされるだけなので、クライアントは update を読み取りと同じようにリトライします。
レスポンス：ドメイン（domains->get）
objectstring- 常に文字列 `domain` です。`list` の行でもこのオブジェクトでも同じです。
idstring- ドメインの UUID。行の存続中は不変で、他のドメイン系呼び出しが受け取る唯一のハンドルです。
domainstring- 小文字のホスト名だけ、つまり `example.com` です。製品全体で一意でドメインごとに所有者は 1 つなので、2 つのワークスペースが同じドメインを主張することはできません。
receiving.verifiedbool- DNS 上で、そのドメインの MX がメールをここへ運ぶホストを指していることが確認され、行がチャレンジトークンを持つ場合は対応する `_openemail-challenge` TXT レコードも確認できた時点で true になります。当社が受信するすべてのドメインが同じホスト名を公開するため MX だけでは何も証明できず、だからトークンが存在し、だからこのフラグが、受信配送がメールを受け入れる前に確認する関門になっています。
receiving.verifiedAtstring or null- 検証が通った時刻で、ISO 8601 の文字列です。通っていない間は null で、`verified` はまさにこのカラムから導出されるので、両者が食い違うことはありません。
receiving.catchAllbool- 任意のローカルパートを受け入れるかどうか。これが規定になって以降に追加されたドメインでは既定でオンです。オフの場合、そのドメイン上に登録されたアドレスだけが受け入れられ、残りは SMTP の時点で拒否されるので、送信者は沈黙ではなくバウンスを受け取ります。
receiving.lastCheckedAtstring or null- このドメインについて最後に DNS に問い合わせた時刻。一度も問い合わせていない場合は null で、1 分前にドメインを追加した人にとって、これは失敗とはまったく違う意味に読めます。未検証のドメインを読み取ると、直前のチェックから 20 秒以上経っていれば DNS に再び問い合わせるため、`get` のポーリングは検証を待つ方法の 1 つです。`verify` はすぐにチェックします。
receiving.errorstring or null- 直近のチェックが通らなかった理由を、所有者が行動に移せる言葉で表したもの。`No MX records yet. DNS changes can take a few minutes to spread.` が典型例です。チェックが通れば null になります。導出ではなく保存された値なので、リロードしても定期再チェックでも同じことを言います。
sending.statusstring- 直近のチェックが見た送信側の署名状態：`verified`、`pending`、`failed`、`no_identity`、`unknown` のいずれか。保存済みのチェックから読むので、`sending.checkedAt` がその古さを示します。
sending.canSendbool- このドメインからの送信が今受け付けられるかどうか。1 日より古い否定的な判定は拒否ではなく不明として扱われるので、`status` が `pending` でもこれが true になることがあります。送信前にはこれで分岐してください。false は、このドメインからの `emails->send` が 409 `domain_not_sendable` で拒否されるという意味です。
sending.checkedAtstring or null- 署名状態が最後に確認された時刻で、ISO 8601 の文字列です。一度も確認していない場合は null で、これは失敗とはまったく違う意味に読めます。
sending.errorstring or null- 直近の署名の失敗を言葉で表したもの。通過すれば null になります。
sending.notestring- `sending.status` によって選ばれる 5 つの文のうち 1 つで、その状態がドメイン所有者にとって何を意味するかを行動に移せる言葉で述べます。人が読むための文章なので、分岐はこれではなく `sending.canSend` で行ってください。
trackingarray- ドメイン独自のトラッキングドメイン。`list` の行でもこのオブジェクトでも同じで、`update` が変更する対象です。
tracking.hoststring or null- `links.acme.com` のようなトラッキングドメイン。設定されていなければ null です。
tracking.statusstring- `none` はトラッキングドメインが設定されていないこと、`pending` は一度もチェックを通っていないこと、`active` は新しいメールがそれを使っていること、`failed` は以前は通っていたが使われなくなったことを意味します。稼働中のホストは、3 回連続でチェックに失敗するか、最後に成功したチェックから 2 時間以上経つと使われなくなります。
tracking.activebool- `status` が `active` のときだけ true になります。すなわち、そのドメインからの新しいメールのトラッキングリンクと開封ピクセルがそのホストを使っている状態です。
tracking.targetstring- CNAME レコードが指すアドレスで、このトラッキングドメイン専用に用意されたものです。`host` が null の間、および新しいホスト用のアドレスを準備中の間は空文字列になります。
tracking.recordarray or null- 公開すべきレコードで、`type`（常に `CNAME`）、`name`、`value` を持つ配列です。名前は `host`、値は `target` です。トラッキングドメインがない場合、および新しいホスト用のアドレスを準備中の場合は null になるため、`$domain['tracking']['record']['value'] ?? null` で安全に読めます。
tracking.checkedAtstring or null- ホストが最後にチェックされた時刻で、ISO 8601 の文字列です。最初のチェックまでは null です。
tracking.verifiedAtstring or null- 最後にチェックに通った時刻で、ISO 8601 の文字列です。一度も通っていないホストでは null です。
tracking.errorstring or null- 直近のチェックで判明したことを、ドメイン所有者が対処できる言葉で示します。直近のチェックに通った場合、またはまだ一度も実行されていない場合は null です。1〜2 回チェックに失敗したホストはまだ `active` のままで、その理由がここに入ります。
addressesarray- ドメイン上のすべてのアドレス行で、`get` が `list` の行に対して追加する部分です。catch-all のもとで配送処理自身が書いた行も含まれ、それらは catch-all をオフにした瞬間に受け付けられなくなるので、このリストは受信できるものの一覧ではありません。
addresses[].addressstring- 完全なアドレス。保存されたローカルパートとホスト名から再構成し小文字化するので、上の `domain` から乖離することなく常に一致します。
addresses[].enabledbool- false はアドレスを無効にします。無効なアドレスは catch-all がオンでも拒否されます。どちらの行も一覧には載るので、このリストを有効なアドレスの集合として読むのではなく、これで絞り込んでください。
createdAtstring- ドメインの行が追加された時刻で、ISO 8601 の文字列です。ドメインが検証された時刻ではありません。そちらは `receiving.verifiedAt` で、これが入っていてもあちらが null のことがあります。