スレッド、下書き、ラベル

inbox、read、archive、label add などのメールコマンドは人のために書かれています。複数のスレッド ID を一度に受け取り、出力を整形し、ラベル ID を見えないようにします。それぞれがこのページのコマンドを実行します。これらはスレッド、下書き、ラベルの SDK メソッドで、メソッド 1 つにつきコマンドが 1 つあるので、threads.listAttachments は openemail threads list-attachments になります。

メールコマンドでは扱えないものが必要なときにこれらを使います。API が返すとおりのスレッド、メッセージのファイル、下書き、そしてラベルの作成、名前の変更、色の変更、削除です。

• —複数形の名前に加えて openemail thread と openemail draft も使えます。openemail labels には単数形がありません。openemail label はスレッドにラベルを付けるメールコマンドです。
• —動詞にはいつもの別名が使えます。list には ls、get には show と view、create には new と add、update には edit、delete には rm、del、remove です。
• —すべてのフラグは openemail threads list --help のように openemail <namespace> <verb> --help で確認できます。

メールボックス内の会話です。CAHk7pQ2x9LmZ4 のようなスレッド ID は、threads list、openemail inbox、openemail search から得られます。

• —--folder の既定は inbox で、ラベル ID として照合されます。そのため sent、archive、spam、trash、draft、snoozed、starred、unread が使え、bin は trash として扱われ、USER_RECEIPTS のようなユーザーラベルの ID も使えます。何にも一致しないフォルダーは、エラーではなく空のページを返します。
• —--query はアプリの検索構文を受け付け、in:anywhere ですべてのフォルダーを検索します。--label-ids はさらに絞り込みます。スレッドはフォルダーと渡したすべての ID を持っている必要があるためです。--date-from と --date-to は各スレッドの最新のメッセージを見て判断し、両端を含みます。
• —threads get は未送信の下書き返信も isDraft: true の印付きでメッセージに含め、下書きの ID も開けます。
• —threads update には --read、--no-read、または追加か削除するラベルが必要です。削除は追加より先に適用されます。存在しないラベルを指す ID は label_not_found で拒否され、スレッドは何も変わらないので、先にラベルを作成してください。TRASH、SNOOZED、DRAFT は label_not_directly_settable で拒否されます。threads trash と threads snooze を使ってください。
• —threads trash は何も削除せず、スレッドは threads get で読める状態のままですが、スレッドをゴミ箱から戻すコマンドはありません。スヌーズ中のスレッドをゴミ箱に移すと、再表示も取り消されます。
• —threads snooze は <wake-at> をそのまま送るので、Z かオフセット付きの将来の ISO 8601 の日時を指定してください。どちらもない日時はサーバーのタイムゾーンで解釈されます。3h のような遅延は無効として拒否されます。遅延を指定するなら openemail snooze --until 3h を使います。スレッドは 1 時間ごとの処理で再表示されるため最大 1 時間ほど遅れることがあり、必ず受信トレイに戻ります。
• —threads list-attachments はすべてのファイルを丸ごと 1 つのレスポンスで返します。メッセージ ID は threads get の messages から取ってください。保存されたバイト列が見つからない場合 content は空文字列になるので、デコードする前に長さを確認してください。

メールボックスに保存された未送信のメッセージです。下書きの ID は draft- で始まります。

• —drafts list --query は件名、送信者、本文の冒頭を検索し、下書きの外は探しません。older_than:30d などの日付演算子は下書きが最後に保存された日時を見ます。to:、cc:、bcc: は下書きでは何にも一致しません。
• —下書きは DRAFT ラベルの付いたスレッドとして保存されるので、threads get で開くことができ、openemail inbox draft で一覧表示できます。drafts get、update、delete は通常のスレッド ID を 404 で拒否します。
• —何も付けない openemail drafts create は空の下書きを保存します。確認されるのは長さだけです。件名は最大 998 文字、--html と --text はそれぞれ最大 1,000,000 文字で、両方を指定すると --html が残ります。添付ファイル用のフラグはありません。
• —drafts update は送った各フィールドを置き換えます。リストは保存されているものを丸ごと置き換えるので、アドレスを 1 つだけ指定した --to は他のアドレスを外します。また、更新すると下書きの添付ファイルのリストは空になります。
• —--thread-id は下書きの返信先のスレッドを記録しますが、下書き自体はやはり独立したスレッドとして保存されます。
• —drafts create をもう一度実行すると 2 つ目の下書きが保存されます。冪等キーを受け付けないためです。表示名にカンマが含まれていると、壊れた 2 つの受信者に分かれてしまうので、カンマは入れないでください。
• —openemail send --draft <id> --to <address> は下書きを送信します。本文は下書きから取られ、件名も --subject を渡さない限り下書きから取られますが、受信者は指定したものになります。本文、--template、--translate とは併用できません。

スレッドに付けられるラベルです。ユーザーラベルの ID は、USER_ の後に、作成時の名前を大文字にして連続する空白をそれぞれ _ に置き換えたものが続くので、Big Clients は USER_BIG_CLIENTS になります。

• —ID は名前を変えても変わらないので、名前ではなく ID を保存してください。
• —INBOX、STARRED、UNREAD などのシステムラベルは一覧に表示されず、変更も削除もできませんが、threads update では使えます。それらに対する labels get は 404 になります。
• —ワークスペースに作れるユーザーラベルは最大 50 個です。大文字と小文字を区別せずに比較して、他のラベルがすでに使っている名前は label_name_taken で拒否されます。
• —色は #3B82F6 のような 16 進数の値か、gradient:sunset のようなグラデーションのトークンです。--label-color は色全体を JSON で受け取り、--label-color null で色を消去します。
• —ラベルはワークスペースに属するので、名前や色の変更、削除はワークスペースの全員に反映されます。
• —labels delete は元に戻せません。同じ名前でラベルを作り直すと同じ ID になりますが、スレッドにラベルは戻りません。labels get の threadCount で、いくつの会話からラベルが外れるかがわかります。

• —メールコマンドは複数のスレッド ID を受け取ってそれぞれについて報告し、--json を付けると { results, succeeded, failed } を出力します。このページのコマンドは ID を 1 つ受け取り、API が返すものを出力します。
• —openemail inbox は、最後に書いた人と件名を表示するために、一覧にするすべてのスレッドを読みます。threads list はページごとに 1 回リクエストし、ID だけを出力します。パイプラインにはそれで十分です。
• —openemail read は HTML のメッセージをテキストに変換し、スレッドを既読にします。threads get は API が返すとおりにスレッドを出力し、何も変更しません。

スレッドの既読化、アーカイブ、ラベル付けを 1 回のリクエストで行います。mark read、archive、label add では 3 回になります：

openemail threads update CAHk7pQ2x9LmZ4 --read --add-label-ids ARCHIVE,USER_RECEIPTS --remove-label-ids INBOX --json

ラベルを作り、一致するすべてのスレッドをそのラベルで整理します。パイプすると、--all は 1 行に 1 つの JSON オブジェクトを出力します：

openemail labels create --name Receipts --color-background-color gradient:meadowopenemail threads list --query "in:anywhere subject:receipt newer_than:1y" --all | jq -r .id | xargs openemail label add --label USER_RECEIPTS

メッセージからファイルを 1 つ保存します。メッセージ ID は threads get の messages にあります：

openemail threads get CAHk7pQ2x9LmZ4 --json | jq -r ".messages[].id"openemail threads list-attachments CAHk7pQ2x9LmZ4 message_4c1b257a --json | jq -r '.[] | select(.filename == "invoice.pdf") | .content' | base64 --decode > invoice.pdf

下書きを書き、変更し、読み返してから送信します：

DRAFT=$(openemail drafts create --to [email protected] --subject "Engine notes for Thursday" --html "<p>Agenda below.</p>" --json | jq -r .id)openemail drafts update "$DRAFT" --to [email protected],[email protected]openemail drafts get "$DRAFT"openemail send --draft "$DRAFT" --from [email protected] --to [email protected],[email protected]

30 日間誰も保存していない下書きを片付けます。ドライランは各 DELETE を送らずに表示し、--yes が確認に答えます：

openemail drafts list --query older_than:30d --all | jq -r .id > stale.txtxargs -n 1 openemail drafts delete --dry-run < stale.txtxargs -n 1 openemail drafts delete --yes < stale.txt

パレットからグラデーションを選び、変更をプレビューしてから適用し、後で色を外します：

openemail labels list-colors --json | jq -r '.[] | select(.kind == "gradient") | .value'openemail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:aurora --dry-runopenemail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:auroraopenemail labels update USER_RECEIPTS --label-color null

スコープが足りない場合は終了コード 4 で停止します。これらのコマンドはどれも、ブラウザでのサインインでも API キーでも確認コードを求めません。

一部のアドレスに限定されたサインインやキーには、それらのアドレスに届いたスレッドしか見えず、それ以外のスレッドは存在しないかのように 404 になります。ラベルはワークスペースに属するので、すべてのラベルは見えますが、threadCount が数えるのは見える会話だけです。

• —threads list、drafts list、labels list は 1 ページを読みます。--limit で指定しない限り 25 件で、最大 100 件です。--cursor は、ページが表示したカーソルから続けます。スレッドのカーソルは発行されたときの並び順を保つので、同じ絞り込み条件と一緒に渡してください。
• —--all はすべてのページを読み、--max <n> はその件数で停止します。パイプしたときや --ndjson を付けたときは 1 行に 1 つの JSON オブジェクトを、--json を付けたときは 1 つの { items, hasMore, nextCursor } ドキュメントを出力します。
• —結果的に最後のページだった場合でも hasMore が true になることがあり、その場合は次の呼び出しで項目が返りません。ページをめくっている間に新しいメールが届いたスレッドはカーソルより前に移り、以降のページでは返されません。ページをめくっている間に保存された下書きも同様です。
• —threads trash、drafts delete、labels delete は確認を求めます。--json や --no-input を付けたとき、またはターミナルがないときの無人実行では、--yes を渡さない限り終了コード 2 で停止し、何も変更しません。
• —--dry-run はコマンドが送るはずのリクエストを認証情報を伏せて表示し、送信も確認もせずに終了コード 0 で終了します。--json を付けると { dryRun, request } を出力します。

--data は本文全体を JSON で受け取ります。インラインでも、@path でファイルからでも、- で stdin からでも渡せ、併せて渡したフラグは対応するキーを上書きします。

フラグの値が空だと使い方のエラーになるので、空の値で消去するフィールドは代わりに --data で渡します。--label-color null はラベルの色を消去します。

openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"from":""}'openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"threadId":""}'openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"to":[]}'openemail drafts create --data @draft.json --subject "Overrides the file"

1 つ目は送信者なしで下書きを保存し、2 つ目は返信先のスレッドから切り離し、3 つ目は受信者を消去します。

openemail threads --helpopenemail threads list --helpopenemail drafts create --help --json

openemail <namespace> <verb> --help は、各引数とフラグをその型とともに表示し、呼び出しに必要なスコープ、メソッドとパス、返す内容、API リファレンスの注記も示します。--json を付けると、同じヘルプをデータとして出力します。