SDK

ドメイン

`domains.list`、`get`、`update`。

すべてのメソッド

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 })

受信と送信は独立した 2 つの事実であり、2 つのオブジェクトとして返されます。receiving.verified は、そのドメインの MX がメールをここへ運び、所有権チャレンジが公開されていることを意味します。sending は送信側の署名チェックを報告します。status は verified、pending、failed、no_identity、unknown のいずれかで、canSend は今そのドメインからの送信が受け付けられるかどうかを示します。1 日より古い否定的な判定は拒否ではなく不明として扱われるので、status ではなく canSend で分岐してください。

update は、ドメイン独自のトラッキングドメイン（links.acme.com のようなサブドメイン）を設定・再チェック・削除し、get と同じ DomainDetailResource に解決されます。tracking はすべての読み取りでその状態を報告します。チェックが通るまで tracking.status は pending で、トラッキングリンクと開封ピクセルは既定の OpenEmail ホストを使い続けます。チェックが通ると active になり、そのドメインからの新しいメールは両方にトラッキングドメインを使います。

get はドメイン上のアドレスも一覧します。関連する呼び出しは addresses.list() で、そちらはこのキーが From ヘッダーに入れてよいアドレスだけという、より狭い一覧です。

パラメーター: domains.get

domainIdstring必須: `domains.list` から得られる id で、ドメインが追加されたときに発行された UUID です。ホスト名ではないので `get('example.com')` では何も見つかりません。検索は id だけでなくキー自身の接続にもスコープされるので、他のワークスペースのドメインは 403 ではなく 404 になります。

パラメーター: domains.update

idstring必須: `get` が受け取るのと同じドメイン id です。必要なスコープは `domains:write` です。
patch.trackingHoststring | null必須: そのドメインのサブドメインで、最大 512 文字。たとえば `links.acme.com` です。トリムして小文字化され、先頭の `https://` や `http://`、パス、末尾のドットは取り除かれます。新しい値は同じ呼び出しの中で検証・保存・チェックされます。ドメインがすでに持っている値を渡すと、直前のチェックから 30 秒未満でない限り、チェックが再実行されます。`null` または空文字列でトラッキングドメインを削除します。

拒否されたホストは、param に trackingHost を名指しする OpenEmailApiError を投げます。ドメイン外の名前など使用できない名前は 422 invalid_tracking_host、receiving.verified が false でドメインの _openemail-challenge TXT レコードがまだ公開されていない状態での新しいホストは 409 domain_not_verified、他のドメインがすでに使っている名前や、別の OpenEmail サーバーが管理しているトラッキングドメインは 409 tracking_host_in_use です。特定のアドレスに限定されたキーは 422 capability_unsupported になります。トラッキングドメインはドメイン上のすべてのアドレスに適用されるからです。

レスポンス: DomainDetailResource

object'domain': 常に文字列 `domain` です。`list` の行でもこのオブジェクトでも同じです。
idstring: ドメインの UUID。行の存続中は不変で、他のドメイン系呼び出しが受け取る唯一のハンドルです。
domainstring: 小文字のホスト名だけ、つまり `example.com` です。製品全体で一意でドメインごとに所有者は 1 つなので、2 つのワークスペースが同じドメインを主張することはできません。
receiving.verifiedboolean: DNS 上で、そのドメインの MX がメールをここへ運ぶホストを指していることが確認され、行がチャレンジトークンを持つ場合は対応する `_openemail-challenge` TXT レコードも確認できた時点で true になります。当社が受信するすべてのドメインが同じホスト名を公開するため MX だけでは何も証明できず、だからトークンが存在し、だからこのフラグが、受信配送がメールを受け入れる前に確認する関門になっています。
receiving.verifiedAtstring | null: 検証が通った時刻、ISO-8601。通っていなければ null です。`verified` はまさにこのカラムから導出されるので、両者が食い違うことはありません。
receiving.catchAllboolean: 任意のローカルパートを受け入れるかどうか。これが規定になって以降に追加されたドメインでは既定でオンです。オフの場合、そのドメイン上に登録されたアドレスだけが受け入れられ、残りは SMTP の時点で拒否されるので、送信者は沈黙ではなくバウンスを受け取ります。
receiving.lastCheckedAtstring | null: このドメインについて DNS に最後に問い合わせた時刻。null は一度も見ていないという意味で、1 分前にドメインを追加した人にとっては失敗とまったく読み方が違います。このエンドポイントは保存された結果を報告するだけで、自分でチェックを実行することはありません。
receiving.errorstring | null: 直近のチェックが通らなかった理由を、所有者が行動に移せる言葉で表したもの。`No MX records yet. DNS changes can take a few minutes to spread.` が典型例です。通れば null になります。導出ではなく保存された値なので、リロードしても定期再チェックでも同じことを言います。
sending.status'verified' | 'pending' | 'failed' | 'no_identity' | 'unknown': 直近のチェックが見た送信側の署名状態。このリクエストで探りにいくのではなく保存済みのチェックから読むので、`sending.checkedAt` がその古さを示します。
sending.canSendboolean: このドメインからの送信が今受け付けられるかどうか。1 日より古い否定的な判定は拒否ではなく不明として扱われるので、`status` が `pending` でもこれが true になることがあります。送信前にはこれで分岐してください。false は、このドメインからの `emails.send` が 409 `domain_not_sendable` で拒否されるという意味です。
sending.checkedAtstring | null: 署名状態が最後に確認された時刻、ISO-8601 です。null は一度も確認していないという意味で、失敗とはまったく読み方が違います。
sending.errorstring | null: 直近の署名の失敗を言葉で表したもの。通過すれば null になります。
sending.notestring: `sending.status` によって選ばれる 5 つの文のうち 1 つで、その状態がドメイン所有者にとって何を意味するかを行動に移せる言葉で述べます。人が読むための文章です。分岐はこれではなく `sending.canSend` で行ってください。
trackingDomainTracking: ドメイン独自のトラッキングドメイン。`list` の行でもこのオブジェクトでも同じで、`update` が変更する対象です。
tracking.hoststring | null: `links.acme.com` のようなトラッキングドメイン。設定されていなければ null です。
tracking.status'none' | 'pending' | 'active' | 'failed': `none` はトラッキングドメインが設定されていないこと、`pending` は一度もチェックを通っていないこと、`active` は新しいメールがそれを使っていること、`failed` は以前は通っていたが使われなくなったことを意味します。稼働中のホストは、3 回連続でチェックに失敗するか、最後に成功したチェックから 2 時間以上経つと使われなくなります。
tracking.activeboolean: `status` が `active` のときだけ true になります。そのとき、そのドメインからの新しいメールのトラッキングリンクと開封ピクセルがそのホストを使います。
tracking.targetstring: CNAME レコードが指す先のアドレスで、このトラッキングドメイン専用に用意されます。`host` が null の間、および新しいホスト用のアドレスを準備している間は空文字列です。
tracking.record{ type: 'CNAME'; name: string; value: string } | null: 公開すべきレコード。名前は `host` に由来し、値は `target` です。トラッキングドメインがないとき、および新しいホスト用のアドレスを準備している間は null です。
tracking.checkedAtstring | null: ホストが最後に確認された時刻、ISO-8601。最初のチェックまでは null です。
tracking.verifiedAtstring | null: チェックが最後に成功した時刻、ISO-8601。一度も成功していないホストでは null です。
tracking.errorstring | null: 直近のチェックが何を見つけたかを、ドメイン所有者が行動に移せる言葉で表したもの。直近のチェックが成功した場合、またはまだ一度も走っていない場合は null です。1 回か 2 回失敗しただけのホストはまだ `active` で、理由はここに入ります。
addressesArray<{ address: string; enabled: boolean }>: ドメイン上のすべてのアドレス行で、`get` が `list` の行に対して追加する部分です。catch-all のもとで配送処理自身が書いた行も含まれ、それらは catch-all をオフにした瞬間に受け付けられなくなるので、この配列は受信できるものの一覧ではありません。
addresses[].addressstring: 完全なアドレス。保存されたローカルパートとホスト名から再構成し小文字化するので、上の `domain` から乖離することなく常に一致します。
addresses[].enabledboolean: false はアドレスを無効にします。無効なアドレスは catch-all がオンでも拒否されます。どちらの行も一覧には載るので、この配列を有効なアドレスの集合として読むのではなく、これで絞り込んでください。
createdAtstring: ドメインの行が追加された時刻、ISO-8601。検証された時刻ではありません。そちらは `receiving.verifiedAt` で、これが入っていてもあちらが null のことがあります。