ファイル、インポート、設定

メールそのものの周辺にあるものは 5 つの名前空間で扱います。openemail files は「ファイル」ページにあたり、送受信したすべての添付ファイルとアップロードしたすべてのファイルを、そのバイト列と送信時のダウンロードリンクとともに扱います。openemail imports は古いメールボックスを 1 つのアドレスに取り込み、openemail provider-imports は Resend アカウントを移行します。openemail calendar はメールから見つかったイベントを読み、openemail settings はメールボックスの環境設定と、各アドレスの署名とトラッキングを読み取り、変更します。

• —ID を見れば何を指すかがわかります。ファイルは file_、メールボックスのインポートは imp_、Resend のインポートは pimp_、カレンダーのイベントは cal_ で、それぞれの後に 16 進数 24 文字が続きます。ダウンロードリンクには独自の ID があり、files list-links や files create-link から得られます。
• —インポートの --address-id は、アドレスそのものではなく、openemail domains list-addresses <id> から得られるアドレスの ID です。
• —名前空間は file、import、provider-import または providerImports、setting でも使えます。動詞には、ある場合はいつもの別名が使えます。list には ls、get には show と view、create には new と add、settings update には edit、files delete には rm、del、remove です。
• —これらのコマンドはどれも、ブラウザでのサインインに確認コードを求めません。何かを恒久的に変更するコマンドは確認を求め、スクリプトでは --yes が代わりに答えます。
• —openemail <command> --help は、すべての引数とフラグを、その型、呼び出しに必要なスコープ、メソッドとパス、返ってくるものとともに一覧表示します。--json を付けると、同じページをデータとして出力します。

openemail files はメールボックスが保持するすべてのファイルを読み取り、管理します。受信した添付ファイル、送信した添付ファイル、「ファイル」ページにアップロードしたファイルです。openemail open files で Web アプリの同じページが開きます。

• —files list は --q（名前と種類）、--kind（image、pdf、audio、video、text）、--direction（inbound、outbound、uploaded）、--address、--since、--until で絞り込み、--sort（newest、oldest、largest、name）で並べ替えます。--since と --until は ISO 8601 の日付または日時を受け取ります。--since はその時点を含み、--until はその直前までです。
• —削除できるのは何にも使われていないアップロードだけで、deletable で事前にわかります。usage は、それ以外のファイルが残される理由を示します。received、sent、ダウンロードリンクがまだ有効なアップロードなら linked、まだ送られていないメッセージに添付されたものなら scheduled です。delete はそれらを 409 file_in_use で拒否します。delete-many は削除できるものを削除し、残りをそれぞれの理由とともに kept に、不明な ID を missing に一覧表示します。
• —upload は指定したパスのファイルを読み、そのファイル名で、拡張子が示す種類として保存します。--filename と --content-type でそれらを上書きできます。stdin からの場合、- には --filename が必要で、--content-type がなければ種類は application/octet-stream になります。アップロードは最大 10 分待ち、--timeout-ms で変更できます。
• —upload が返す ID を openemail emails send --attachments で { "fileId": "…" } として指定すると、そのファイルを送信に添付できます。インラインの上限である 5 MB を超えるファイルはこの方法で送ります。
• —空のファイルは 400 upload_empty、プログラムやスクリプト（名前で判断）は 400 upload_dangerous、100 MB を超えるファイルは 413 upload_too_large になります。ワークスペースには最大 10 GB のアップロードを保存でき、1 時間に 500 件までアップロードできます。
• —download はターミナルでは --out <file> が必要で、なければ終了コード 2 で停止します。パイプした場合、バイト列は stdout に出力され、--out - でも stdout を指定できます。ファイル全体がメモリに保持されます。
• —create-link は呼び出すたびに独自のダウンロード数を持つ新しいリンクを作り、リンクは取り消されるかファイルが削除されるまで有効です。リンクは、--domain のドメインにファイル用ドメイン（files.acme.com など）があればそこに、なければファイルのアドレスのファイル用ドメインに、それもなければ API のアドレスに置かれます。プログラムやスクリプトは 422 file_unshareable で拒否されます。
• —revoke-link は繰り返しても安全です。すでに取り消されたリンクは変更されずに返ります。
• —特定のアドレスやドメインに限定されたキーやサインインには、それらに届いたファイルしか見えず、ワークスペース全体にアップロードされたファイルは見えません。また、そのキーやサインインでのアップロードは、それが持つ最初のアドレスに属します。
• —ファイルのインデックスは、その機能が公開された日から始まります。それより古い添付ファイルは元のメッセージに残っており、openemail threads list-attachments <id> で読めます。

openemail imports は古いメールボックスを 1 つのアドレスに取り込みます。Google Takeout のアーカイブ、Apple Mail、Thunderbird、たいていのデスクトップアプリの .mbox ファイル、.eml ファイル、そしてそれらを含む .zip や .tgz のアーカイブで、1 ファイル最大 100 GB、1 回のインポートで最大 50 ファイルです。スレッド、日付、ラベルも引き継がれます。インポートされたメールは静かで、ルール、転送、通知、要約、Webhook は一切実行されません。

ほとんどの人に必要なのは import-files です。インポートを作成し、進捗を表示しながらすべてのファイルを分割してアップロードし、開始します。他の動詞はその手順を 1 つずつ行うもので、止まったアップロードを完了させたり、自分で操作したりするときに使います。create は計画、chunkBytes、各ファイルの chunks を返し、upload-chunk は 1 つのパートを送り、upload-state はどのパートが届いたかを示し、start はインポートをキューに入れます。openemail open imports で Web アプリの同じインポートを表示できます。

• —アドレスは、ワークスペース自身のドメインにあり、キーやサインインが操作を許されているものでなければなりません。インポートは 1 つのアドレスにつき 1 つしか実行されず、キュー待ちまたは実行中のものがある間に別のものを始めると 409 already_running になります。
• —import-files は --files をファイルごとに 1 回、またはカンマ区切りの複数のパスで受け取り、それぞれを元のファイル名で送ります。--options は {"keepInbox":false,"includeSpam":true} のような JSON を受け取ります。create では同じ 3 つがスイッチになっていて、--options-keep-inbox、--options-include-spam、--options-include-trash です。それぞれ --no-options-keep-inbox のように前に --no- を付けるとオフになります。
• —keepInbox は既定でオンなので、古い受信トレイのメールは未読状態を保ったまま受信トレイに入ります。オフにするとすべてがアーカイブに入ります。迷惑メールとゴミ箱は、含めない限り取り込まれません。
• —create は --files を JSON で、インラインまたは @path でファイルから受け取り、各 bytes はその後アップロードするファイルの正確なサイズでなければなりません。
• —各パートはファイルの最後のパートを除いてちょうど chunkBytes の長さで、長さが違うパートは 400 bad_chunk になります。start は、パートが欠けているファイルを 412 missing_chunks で、アーカイブでもメールボックスでもないファイルを 400 unsupported_file で拒否します。すでに uploading を過ぎたインポートでは、インポートを変更せずに返します。
• —再試行してもパートが失敗する場合、import-files はインポートを uploading のままにして停止します。下のブロックは、最初のファイルの不足しているパートを送り、インポートを開始します。
• —インポートは totalBytes のうちの processedBytes と、seen、imported、duplicate、filtered、failed、threads を含む counts を報告します。lastError が設定されるのは status が failed のときだけです。
• —list-failures は各失敗に reason を付けます。too-large（50 MB 超）、unparseable、no-date、storage-error、unreadable-entry、encrypted-entry、archive-limit のいずれかで、読み取れた場合は件名と送信者も示します。
• —完了したインポートに対する cancel は 409 not_cancellable になります。delete-upload はまだアップロード中のインポートを取り消しますが、キュー待ちまたは実行中のものは 409 still_running で拒否するので、先にそれを取り消してください。

openemail imports get "$import_id" --json > import.jsonopenemail imports upload-state "$import_id" --json > state.jsonchunk=$(jq .chunkBytes import.json)chunks=$(jq '.files[0].chunks' import.json)for i in $(seq 0 $((chunks - 1))); do  jq -e --argjson i "$i" '.received[0] | any(. == $i)' state.json > /dev/null && continue  dd if=takeout-001.zip bs="$chunk" skip="$i" count=1 2> /dev/null |    openemail imports upload-chunk "$import_id" 0 "$i" -doneopenemail imports start "$import_id"

openemail provider-imports は、フルアクセスの Resend API キー 1 つで、ワークスペースを Resend から移行します。抑止は理由を保ち、セグメントはオーディエンスになり、購読中の連絡先は名前付きで届き、テンプレートは変数が宣言された HTML テンプレートとして届きます。ここでの配信は署名の方式が異なるため、Webhook はオフの状態で登録されます。署名鍵やトークンは Resend から持ち出せないので、ドメインと API キーは代わりにレポートのチェックリストとして返されます。

• —Resend のキーは、ファイルから読むには @path として、stdin から読むには - として渡してください。そうすればシェルの履歴やプロセス一覧に残りません。コマンドラインに直接入力したキーも使えますが、警告が出ます。--dry-run はキーを伏せた本文を表示します。
• —--resources は suppressions、audiences、contacts、templates、webhooks、domains、api-keys のいずれかを、カンマ区切りまたは繰り返しで受け取ります。
• —送信専用のキーは 400 restricted_key になります。インポート用に Resend でフルアクセスのキーを作成し、終わったら取り消してください。
• —inspect は各リソースの最初のページを読み、リソースごとに 1 つの { count, more } を含む counts を返します。リソースが最初のページに収まらない場合は more が設定されます。
• —インポートは 1 つのワークスペースにつき同時に 1 つしか実行されず、2 つ目は 409 already_running になります。同じインポートを 2 回実行しても何も重複しません。キーはインポートの実行中だけ暗号化して保持され、終了、失敗、取り消しのいずれかで消去されます。
• —Resend で配信停止した連絡先は除外され、report.contacts.unsubscribed で数えられます。
• —report.domains は Resend の各ドメインを state とともに一覧表示します。このワークスペースにない場合は absent、あるが未検証の場合は added、そして verified で、Resend にあったレコードも示します。ないドメインは openemail domains create で追加してください。report.apiKeys は openemail keys create で作り直すべきキーを示します。
• —ブラウザでのサインインでは、これらのコマンドを使えるのはワークスペースのオーナーだけで、メンバーには 403 owner_only が返ります。API キーにはこの制限はありません。特定のアドレスやドメインに限定されたキーやサインインは、インポートの調査も作成もできません。オーディエンス、抑止、テンプレートはワークスペース全体に属するからです。
• —create には、取り込む各リソースのスコープも必要です。オーディエンスには audiences:write、連絡先には contacts:write と audiences:write、テンプレートには templates:write、Webhook には webhooks:write、ドメインには domains:read です。

openemail calendar はメールから見つかったカレンダーのイベントを読みます。3 つのコマンドはどれも読み取るだけです。list-events は、指定した期間内で各イベントを個々の発生に展開するので、毎週の会議は 1 週につき 1 行になります。get-event と get-event-ics は 1 つのイベント全体を読みます。openemail open calendar で Web アプリのカレンダーが開きます。

• —--from と --to は 2026-10-01T00:00:00Z のような ISO 8601 の日時です。繰り返しのシリーズには一覧の終わりがないため、--to は --from より後で、かつ最大 366 日後まででなければなりません。境界がない場合は 422 invalid_parameter です。解析できない境界、逆転したり長すぎたりする期間、不明なタイムゾーンは 400 invalid_parameter です。
• —--timezone は Europe/London のような IANA タイムゾーンで、省略すると UTC です。独自のタイムゾーンなしで保存されたイベントの展開に使われ、終日イベントがどの日になるかを決めます。
• —get-event と get-event-ics は、iCalendar の uid ではなく、発生の eventId を受け取ります。繰り返しのシリーズは 1 つのイベントなので、その start と end は最初の回を表します。
• —取り消されたイベントも status が CANCELLED として一覧に表示されます。myPartstat は、ワークスペースが自身のドメインで持つアドレスについて記録された回答で、どれも参加者でない場合は null です。
• —ページングは --cursor と同じ期間で続けます。特定のアドレスに限定されたキーやサインインには、それらのアドレスのどれかが主催または参加するイベントしか見えず、それ以外のイベントは 404 になります。
• —get-event-ics は METHOD:PUBLISH を宣言するので、インポートすると承諾や辞退を求めるのではなく、イベントが現状のまま表示されます。時刻指定のイベントは UTC の日時として、終日イベントは日付として書き出されます。DTSTAMP はダウンロードした時刻なので、変更のないイベントを 2 回ダウンロードするとその行だけが異なります。

openemail settings は、タイムゾーン、言語、時刻の形式、ブロックリストなど、メールボックスの環境設定を読み取り、変更します。4 つの設定はワークスペースではなくアドレスに属します。signature、openEmailSignature（OpenEmail のフッター）、trackOpens、trackClicks です。アドレスは --address で指定し、ドメインのキャッチオールには *@acme.com を使います。

• —--address なしの場合、get はアドレスごとの 4 つの設定を組み込みの既定値として読みます。署名なし、OpenEmail のフッターはオン、開封とリンクのトラッキングはオンです。付けた場合は、まずアドレス自身の値、次にキャッチオールがそのアドレスを拾った場合はドメインのキャッチオールの値、最後に既定値が使われます。独自の設定を持たないプラスアドレスは、元のアドレスの設定を読みます。
• —--address なしの場合、update は --signature、--open-email-signature、--track-opens、--track-clicks を 422 address_required で拒否し、何も書き込みません。付けた場合、update はその 4 つだけを受け付け、それ以外は 422 not_per_address になります。アドレスはこのワークスペースにあるか、キャッチオールがオンになっているここの検証済みドメインの *@domain でなければなりません。
• —スイッチは前に --no- を付けるとオフになります。--no-open-email-signature、--no-track-opens、--no-track-clicks です。
• —--signature は最大 150,000 文字の HTML で、書き込み時にサニタイズされるので、返ってくるものがそのまま送信されます。空文字列で削除されます。送信時に追加するかどうかは送信側で決まります。openemail emails send --help の --signature を参照してください。
• —フラグはよく使うフィールドをカバーしています。--data は timeFormat、weekStart、undoSendEnabled、blockedSenders、blockedDomains など、保存されている任意の設定を JSON で、インラインで、@path でファイルから、または - で stdin から受け取ります。設定が知らないキーはエラーなしで捨てられ、既知のキーで型が違うものは 422 invalid_parameter になります。
• —blockedDomains のようなリストは丸ごと置き換えられるので、下の例のように、まず読んでから変更を加えて送り返してください。ルールにするには短すぎるブロックリストのエントリは 422 blocklist_entry_too_broad になります。
• —--timezone と --language は確認されずに指定どおり保存されるので、送る前にタイムゾーンや言語コードを確認してください。
• —プライバシーのフィールドである externalImages、trustedSenders、blockedSenders、blockedDomains、blockedWords、useDefaultBlockedWords はワークスペースに属します。特定のアドレスやドメインに限定されたキーやサインインはこれらを変更できず、--address には自分が持つアドレスか、全体を持つドメインのキャッチオールしか指定できません。どちらの拒否も 422 capability_unsupported です。
• —何も含まない更新は何も変更せず、現在の設定を返します。defaultEmailAlias は Web アプリの作成画面で From のアドレスをあらかじめ選択するだけで、API が送信者を選ぶのに使うことはありません。

file_id=$(openemail files upload ./price-list.pdf --json | jq -r .id)openemail files create-link "$file_id" --domain acme.com --json | jq -r .urlopenemail files list-links "$file_id"openemail files download "$file_id" --out copy.pdf

create-link は実行するたびに新しいリンクを作るので、1 回だけ実行し、リンクは list-links で読み直してください。revoke-link は後でそのリンクを止め、すでに送ったメール内のものも止めます。

openemail files list --direction uploaded --all | jq -r 'select(.deletable) | .id' > deletable.txtwc -l < deletable.txtxargs -r -n 100 openemail files delete-many --yes --json < deletable.txt | jq -c '.kept[]'

パイプで --all を使うと、files list は 1 行に 1 つのファイルを出力します。xargs -n 100 は delete-many に 1 回の呼び出しで最大 100 個の ID を渡し、その間に使われるようになったファイルは、呼び出しを失敗させる代わりに理由とともに kept で返されます。

domain_id=$(openemail domains list --all | jq -r 'select(.domain == "acme.com") | .id')address_id=$(openemail domains list-addresses "$domain_id" --all | jq -r 'select(.address == "[email protected]") | .id')openemail imports import-files --address-id "$address_id" --files ~/Downloads/takeout-001.zip --files ~/Downloads/takeout-002.zip --json > import.jsonimport_id=$(jq -r .id import.json)until openemail imports get "$import_id" --json | jq -e '.status != "queued" and .status != "running"' > /dev/null; do  sleep 60doneopenemail imports get "$import_id" --json | jq '{status, counts, lastError}'openemail imports list-failures "$import_id" --json | jq -r '.data[] | [.reason, .subject] | @tsv'

import-files の --dry-run は、送るはずの POST /imports を各ファイルの名前とサイズとともに表示し、何もアップロードしません。list-failures は 100 件ずつ読みます。次のページには、表示された nextCursor を --after として渡してください。

openemail provider-imports inspect @resend-key.txtopenemail provider-imports create --resend-key @resend-key.txt --resources suppressions,audiences,contacts,templates,webhooks,domains,api-keys --json > resend.jsonpimp_id=$(jq -r .id resend.json)until openemail provider-imports get "$pimp_id" --json | jq -e '.status != "queued" and .status != "running"' > /dev/null; do  sleep 10doneopenemail provider-imports get "$pimp_id" --json | jq '.report | {contacts, domains: [.domains[] | {name, state}], apiKeys: [.apiKeys[].name]}'

openemail calendar list-events --from 2026-10-01T00:00:00Z --to 2026-11-01T00:00:00Z --timezone Europe/London --all |  jq -r 'select(.status != "CANCELLED") | [.start, .summary, .myPartstat] | @tsv'openemail calendar get-event cal_8d3f0a2b9c4e41f7a6b5c2d1 --json | jq '.attendees[] | {email, partstat}'openemail calendar get-event-ics cal_8d3f0a2b9c4e41f7a6b5c2d1 --out standup.ics

openemail settings get --address [email protected] --json | jq '{signature, openEmailSignature, trackOpens, trackClicks}'openemail settings update --address [email protected] --signature "$(cat signature.html)" --no-track-clicks --dry-runopenemail settings update --address [email protected] --signature "$(cat signature.html)" --no-track-clicksopenemail settings update --address '*@acme.com' --no-track-opensopenemail settings update --timezone Europe/London --language enopenemail settings get --json | jq -c '{blockedDomains: ((.blockedDomains + ["spam.example"]) | unique)}' |  openemail settings update --data -

ドライランは PATCH /settings?address=sales%40acme.com とその本文を送らずに表示します。キャッチオールの行は acme.com のキャッチオールが拾うすべてのアドレスのトラッキングを設定し、最後の行は他のドメインを外さずに 1 つのドメインをブロックリストに追加します。

• —スコープのないサインインやキーは終了コード 4 で停止し、足りないスコープの名前と取得方法を示します。
• —files revoke-link、files delete、files delete-many、imports cancel、imports delete-upload、provider-imports cancel は確認を求めます。いいえと答えると終了コード 10 で終了し、何も変更しません。--yes なしの無人実行では、何も送らないうちに終了コード 2 で停止します。
• —ここにあるコマンドは、ブラウザでのサインインでも API キーでも確認コードを求めないので、スクリプトに必要なのは --yes だけです。
• —--dry-run は変更が送るはずのリクエストを本文とともに表示し、送信も確認もせずに終了コード 0 で終了します。ファイルの本文はサイズと種類で表示されます。
• —files list、files list-links、imports list、provider-imports list、calendar list-events は 1 ページを読みます。--limit は 1 から 100 を受け付け、省略するとサーバーは 25 件を返します。--cursor は前のページの nextCursor を受け取ります。--all はすべてのページを読み、--max <n> はその件数で停止し、--ndjson、またはパイプでの --all は 1 行に 1 つの JSON オブジェクトを出力します。--json を付けると 1 つの { items, hasMore, nextCursor } ドキュメントを出力します。
• —imports list-failures は独自の方法でページングします。--after は前のページの nextCursor を受け取り、--limit は最大 100 で、それが既定値です。--all はありません。--json を付けると { object, data, nextCursor } を出力します。
• —読み取りと、2 回行っても同じ結果になる変更は、ネットワーク障害の後に再試行されます。files revoke-link、imports upload-chunk、imports start、settings update です。それ以外の変更は 1 回だけ送られます。応答が失われた後は、もう一度試す前に確認してください。2 回目の upload は 2 つ目のコピーを保存し、2 回目の create-link は 2 つ目のリンクを作ります。2 回目の files delete で 404 が返れば 1 回目が成功したということで、2 回目の delete-many は 1 回目で削除されたものを missing に一覧表示します。
• —拒否された場合は、そのステータスに対応するコードで終了します。403 なら 4、404 なら 5、409 なら 6、400 か 422 なら 7、429 なら 8 です。