ドメインとアドレス

ドメインは 2 つの名前空間で扱います。openemail domains はワークスペースに接続されたドメインを管理します。追加と削除、各ドメインに必要な DNS レコード、受信と送信ができるかどうか、キャッチオール、トラッキング用とファイル用のドメイン、そのドメインのアドレスです。openemail addresses はもっと限られた問いに答えます。使っているキーやサインインが、どのアドレスとして送信できるかです。

• —ドメインのコマンドはドメイン ID を受け取ります。これは domains list や domains create から得られる UUID です。代わりにホスト名を渡すことはできないので、openemail domains get acme.com は 404 になり、終了コード 5 で終了します。
• —アドレスのコマンドは、ドメイン ID の次にアドレス ID を受け取ります。アドレス ID は domains list-addresses や domains create-address から得られる UUID です。
• —domain と address も名前空間の名前として使えます。ドメインの動詞は ls、show、new、edit、rm などのいつもの別名で使え、addresses list も同様です。create-address など、ドメイン上のアドレスを扱う 5 つの動詞には別名がありません。
• —openemail <command> --help は、すべての引数とフラグを、その型、呼び出しに必要なスコープ、メソッドとパス、返ってくるものとともに一覧表示します。--json を付けると、同じページをデータとして出力します。

ドメインは互いに独立した 2 つの事実を報告します。receiving.verified は、公開 DNS がそのドメインの MX レコードと _openemail-challenge TXT レコードを返すようになると true になり、それ以降メールを受信します。sending.status は、最後の確認で見た署名の状態で、verified、pending、failed、no_identity、unknown のいずれかです。sending.canSend は、今そのドメインからの送信が受け付けられるかどうかを示し、1 日より古い否定的な判定は不明として扱われます。そのためスクリプトは status ではなく canSend で分岐してください。false の間、そのドメインからの送信は 409 domain_not_sendable で拒否されます。

• —domains create は呼び出しの中で最初の DNS 確認を行うので、records の各エントリにはすでに status があります。found、missing、またはまだ確認されていなければ null です。値はそのドメイン固有なので、すべてのレコードを示されたとおりに正確に公開してください。
• —domains verify はすぐに確認します。前回の確認から 10 秒以内なら新たな確認は行わず、現在の状態のドメインを返します。検証済みのドメインでは署名レコードを再確認するので、sending は最新になります。
• —未検証のドメインに対する domains get は、前回の確認から 20 秒以上たっていれば再確認します。そのため get のポーリングでも使え、verify には domains:write が必要なのに対し、こちらは domains:read だけで済みます。
• —公開したばかりのレコードが公開 DNS に現れるまで数分かかることがあります。

ターミナルでは、get、create、verify は 1 行に 1 フィールドを出力し、receiving、sending、records などの入れ子のブロックはコンパクトな JSON で表示します。下の例のように、--json を付けて jq などのツールで読んでください。

domains update は互いに依存しない 3 つの設定を変更します。省略したフラグの設定はそのまま残り、フラグを 1 つも付けなければドメインは変更されずに返ります。

• —新しいホストは同じ呼び出しの中で保存され、確認されます。応答の tracking または storage ブロックにある record.name という名前と record.value という値で CNAME レコードを公開し、プロキシはすべてオフにしてください。ホストを設定し直すと値が変わることがあるので、最新の応答が示す値を公開してください。
• —確認に合格するまで、ホストは pending と表示され、新しいメールは既定の OpenEmail のホストを使い続けます。合格すると active になります。OpenEmail は自動で確認を続け、有効なホストが 3 回続けて確認に失敗するか、最後に合格した確認から 2 時間たつと failed になり、新しいメールは既定のホストに戻ります。
• —ホストは --tracking-host null のように null で削除します。--tracking-host= のような空の値は CLI では使い方のエラーとなり、終了コード 2 で終了します。
• —新しいホストには、ドメインが検証済みであるか、少なくとも _openemail-challenge TXT レコードが公開されている必要があります。そうでなければ呼び出しは 409 domain_not_verified で拒否されます。
• —フラグは、キャッチオール、トラッキング用ドメイン、ファイル用ドメインの順に適用されます。後のフラグが拒否されても前の変更は保存されたままになることがあるので、それぞれを独立させたい場合は別々の呼び出しで送ってください。

ドメインには、手動または API で作成されたアドレスと、最初にメールが届いたときにキャッチオールが拾ったアドレスがあります。list-addresses は無効なものも含めて両方を表示します。キャッチオール自体は行ではなく、ドメインの receiving.catchAll です。

• —create-address は、@ の前の部分である --local-part と、任意の --label を受け取ります。ドメインはまだ検証されていなくてもかまいませんが、検証されるまでアドレスは何も受信しません。* だけのものは、キャッチオールの書き方なので拒否されます。
• —すでに存在するアドレスや削除されたアドレスを作成してもエラーにはなりません。送ったラベル付き、またはラベルなしで有効な状態で戻り、ID もそのままです。キャッチオールが拾ったアドレスは手動で作成したものになるので、キャッチオールをオフにした後も受信を続けます。
• —キャッチオールがオンのとき、新しいアドレスは、プライバシー設定を除き、署名やトラッキングなどキャッチオールのアドレスごとの設定を引き継いで始まります。設定は 1 回コピーされるだけで、その後は同期されません。
• —update-address --no-enabled はアドレスがメールを受け取るのを止めるので、送信者にはバウンスが返り、そのアドレスからは何も送信できません。メール、設定、アクセスできる人はそのまま残り、--enabled で中断したところから再開します。--label で名前を変更し、--label null で名前を削除します。
• —delete-address はさらに踏み込みます。キャッチオールがオンでもそのアドレス宛てのメールは拒否され、転送は止まり、設定は削除され、アクセス権を与えられていた人はそれを失い、パスワードでのサインインは取り消されます。すでに受信したメールはメールボックスに残ります。もう一度作成すると同じ ID が戻りますが、以前の設定やアクセス権は戻りません。

openemail addresses list は、403 from_address_forbidden の背後にある問い、つまり呼び出しに使っているキーやサインインがどのアドレスを From に入れられるかに答えます。送信が何を受け付けるかを示すものなので、読み取りのスコープではなく emails:send が必要です。

• —ターミナルでは 2 つの表を出力します。まずアドレスで、それぞれが有効かどうかと送信に使えるかどうか、次にドメインで、それぞれ受信と送信について検証済みかどうかと、キャッチオールです。
• —unrestricted は、認証情報が何にも制限されていないときに true になります。その場合、ワークスペースのドメインのどのローカルパートからでも送信でき、誰も作成していないものも含みます。それ以外の場合、canSend が true になるのは、認証情報が持つドメイン全体または自身のアドレスのリストを通じて対象になっている、有効なアドレスだけです。
• —無効なアドレス、認証情報の対象外のアドレス、ドメインがまだ署名できないアドレスでは、canSend は false です。
• —一覧に表示されるのは作成済みのアドレスだけです。ドメイン全体を持つ認証情報は、そのドメインの任意のローカルパートとして送信できます。また、リストにあってもメールボックスのないアドレスは、ここに表示されなくても送信元として使えます。
• —--json を付けると、他のリストが出力する { items, hasMore, nextCursor } ドキュメントではなく、1 ページなら { unrestricted, addresses, domains, hasMore, nextCursor } を、--all なら { unrestricted, addresses, domains } を出力します。パイプで --all を使うか --ndjson を付けると、1 行に 1 つのアドレスを出力します。

openemail status は、サインイン、addresses list、domains list を同時に読み、まとめて出力します。Sender addresses の表には、各アドレスが送信できるかどうかと有効かどうかが表示されます。Domains の表には、各ドメインの受信についての verified または not verified、送信のステータス、キャッチオールが表示されます。それぞれ最初の 100 件を表示し、残りを見るための --all 付きのコマンドを示します。

• —domains:read がない場合のドメインや、emails:send がない場合のアドレスのように、認証情報で読めない部分には理由とともに Not available と表示され、残りはそのまま出力されます。
• —まだアドレスがない場合は、openemail domains create --domain example.com を提案します。
• —openemail status --json は、account、addresses、domains、unavailable を持つ 1 つのオブジェクトを出力します。unavailable には、読めなかった各部分の理由が入ります。

新しいドメインのレコードを自動で書き込むための DNS プロバイダーの連携は、0.0.2 では Web アプリでしか行えません。openemail open providers または open dns でそのページが開きます。open domains はドメインとその DNS レコードを、open addresses はアドレスを開きます。転送も Web アプリにあり、open forwarding <address> で 1 つのアドレスの転送設定を開きます。--print を付けると、ブラウザを開く代わりにリンクを表示します。

openemail domains create --domain acme.com --json > acme.jsonjq -r '.records[] | [.type, .name, .value, (.priority // "")] | @tsv' acme.jsonopenemail domains verify "$(jq -r .id acme.json)"

id=b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6funtil openemail domains get "$id" --json | jq -e .receiving.verified > /dev/null; do  sleep 30doneopenemail domains get "$id" --json | jq '.sending | {status, canSend, error}'

openemail domains list-addresses "$id" --allopenemail domains create-address "$id" --local-part invoices --label Invoicesopenemail domains update "$id" --no-catch-all --dry-runopenemail domains update "$id" --no-catch-all

invoices を手動で作成しておくと、キャッチオールをオフにした後も受信を続け、キャッチオールが拾った他のすべてのアドレス宛てのメールは拒否されます。ドライランは PATCH とその本文を送らずに表示します。

openemail domains update "$id" --tracking-host links.acme.com --json | jq '.tracking | {status, record, error}'openemail domains update "$id" --tracking-host null

address_id=$(openemail domains list-addresses "$id" --all | jq -r 'select(.address == "[email protected]") | .id')openemail domains update-address "$id" "$address_id" --no-enabledopenemail domains delete-address "$id" "$address_id" --yes

先にアドレスをオフにする操作は --enabled で元に戻せます。削除は元に戻せず、スクリプトでは --yes が必要です。ブラウザでサインインしている場合は確認コードも求められ、--yes でそれを省略することはできません。

openemail domains list --all | jq -r 'select(.sending.canSend | not) | [.domain, .sending.status] | @tsv'openemail addresses list --all --json | jq -r '.addresses[] | select(.canSend) | .address'

• —スコープのないサインインやキーは終了コード 4 で停止し、足りないスコープの名前と取得方法を示します。
• —domains delete と domains delete-address は確認を求めます。いいえと答えると終了コード 10 で終了し、何も変更しません。--yes なしの無人実行では、何も送らないうちに終了コード 2 で停止します。
• —ブラウザでサインインしている場合、この 2 つの削除は Web アプリと同じように確認コードも求めます。無人実行では誰も入力できないので、コマンドは終了コード 4 で停止します。先に openemail verify を実行すれば、その後 60 分間はコードが不要です。API キーが求められることはありません。
• —--dry-run は変更が送るはずのリクエストを本文とともに表示し、送信も確認もせずに終了コード 0 で終了します。
• —リストは 1 ページを読みます。--limit は 1 から 100 を受け付け、省略するとサーバーは 25 件を返します。--cursor は前のページの nextCursor を受け取ります。--all はすべてのページを読み、--max <n> はその件数で停止し、--ndjson、またはパイプでの --all は 1 行に 1 つの JSON オブジェクトを出力します。--json を付けると、domains list と list-addresses は 1 つの { items, hasMore, nextCursor } ドキュメントを出力します。
• —特定のドメインやアドレスに限定されたキーやサインインでも、すべてのドメインとアドレスが見えます。ドメインを追加することはできず、それ以外の変更には対象のドメイン全体を持っている必要があり、そうでなければ呼び出しは 422 capability_unsupported で拒否されます。
• —拒否された場合は、そのステータスに対応するコードで終了します。403 なら 4 で、プランでこれ以上ドメインを追加できないときの domain_allowance_reached などです。404 なら 5、409 なら 6 で、domain_already_added や domain_claimed などです。422 なら 7 で、invalid_tracking_host や workspace_limit_reached などです。
• —ワークスペースの最後のドメインは CLI から削除できません。それは 409 last_domain になります。削除するとメールボックス全体が消えるため、Web アプリで先に確認するからです。予約済みのアカウントアドレスを持つドメインは 409 domain_holds_reserved_addresses になります。
• —domains create と 2 つの削除は、ネットワーク障害の後に再試行されることはありません。応答が失われた後の自分での 2 回目の試行で 409 domain_already_added や 404 が返った場合は、1 回目が成功したということです。verify、update、create-address、update-address は 2 回送っても結果が同じなので、自動で再試行されます。