メールの送信とトラッキング

emails 名前空間は送信 API をコマンドにしたもので、SDK の openemail.emails の各メソッドに 1 つずつ対応します。それぞれが 1 つのエンドポイントを呼び出し、返された内容を表示します。tracking 名前空間は、送信したメールの開封とクリックを読み取ります。openemail emails の代わりに openemail email も使えます。

ここにあるすべてのコマンドには、ブラウザまたは API キーによるサインインと、2 つのスコープのどちらかが必要です。送信、翻訳、取り消し、再スケジュールには emails:send、読み取るだけのものにはすべて emails:read です。

openemail send は「メール」のページで説明している手書きのコマンドで、emails send を通して送信します。ターミナルの前にいる人向けに作られており、--from を省略すると送信元アドレスを選び、本文をファイル、stdin、またはエディタから読み取り、パスを指定してファイルを添付し、何かを送る前に確認用の概要を表示します。openemail emails send はリクエストの本文をフィールドごとに 1 つのフラグとして受け取り、何も尋ねないので、何を送るかを正確に把握しているスクリプトに向いています。

emails send だけにあるフラグは次のとおりです。1 回の送信で開封やクリックの追跡をオフにする --tracking、--signature、カスタムヘッダー用の --headers、ファイルを添付するかリンクにするかを選ぶ --attachment-delivery、そして本文全体を JSON で渡す --data です。JSON はインラインでも、@path でファイルからでも、- で stdin からでも渡せます。

send、send-batch、translate、cancel、reschedule には emails:send が、list、get、list-events、get-tracking には emails:read が必要です。メールの ID は、送信が返すとおり、msg_ の後に 16 進数 24 文字が続く形式です。

5 つすべてに emails:read が必要です。tracking get、list-opens、list-clicks は、メッセージが持つどちらの ID でも受け付けます。送信が返した msg_ の ID か、tracking list と Webhook のペイロードに含まれる tmsg_ のトラッキング ID です。

tracking list と get-stats は、Web アプリで書いたメールや MCP ツールやアシスタントが送ったメールを含め、メールボックスが送信したすべての追跡対象メッセージを対象にします。一方、emails list には API が作成した送信記録が入っています。送信記録のないレポートでは sendId が null になります。

独自の冪等キーを付けてスクリプトから送信します。同じ --idempotency-key でもう一度実行すると、2 通目を送る代わりに、最初のメールを replayed: true 付きで表示します。

openemail emails send \  --from 'Acme Billing <[email protected]>' \  --to [email protected] \  --subject 'Your September invoice' \  --html '<p>The invoice is attached. Tell me if anything on it looks wrong.</p>' \  --attachments '[{"fileId":"file_6bb640f5b99e47deb758f1f5"}]' \  --tracking '{"opens":false}' \  --idempotency-key invoice:inv_2026_09_4192 \  --json | jq -r '.id + " " + .status'

送る前に翻訳を人に読んでもらいます。承認された文面は --translate を付けずに、そのまま --subject と --html として送ってください。付けると 2 回翻訳されます。--no-include-original を渡さない限り、翻訳された html にはその下に元の文面がすでに含まれています。

openemail emails translate --to de \  --subject 'Your September invoice' \  --html "$(cat invoice.html)" \  --json > preview.jsonjq -r .html preview.jsonopenemail emails send --from [email protected] --to [email protected] \  --subject "$(jq -r .subject preview.json)" \  --html "$(jq -r .html preview.json)"

ファイルから一括送信します。一部の項目が失敗しても、一括送信が処理されればコマンドは終了コード 0 で終了するので、failed と各項目の status を読んでください。同じキーでもう一度実行すると、送信済みの項目は再生され、残りだけが送られます。ただし配列の順序が変わっていない場合に限ります。

[  { "from": "[email protected]", "to": "[email protected]", "subject": "Receipt 4192", "text": "Thanks for your order." },  { "from": "[email protected]", "to": "[email protected]", "subject": "Receipt 4193", "text": "Thanks for your order." }]

openemail emails send-batch receipts.json --idempotency-key receipts:2026-09-27 --json > result.jsonjq '{ sent, failed }' result.jsonjq -r '.items[] | select(.status == "error") | "\(.index) \(.error.code)"' result.json

メールを予約し、日時を移し、取り消します。--yes は cancel が求める確認に代わりに答えます。スクリプトは確認に答えられないためです。

ID=$(openemail send --from [email protected] --to [email protected] --subject "Standup notes" \  --body-file notes.md --at 2026-10-01T09:00:00Z --json | jq -r .id)openemail emails reschedule "$ID" 2026-10-01T13:00:00Zopenemail emails get "$ID" --json | jq -r '.status + " " + .scheduledAt'openemail emails cancel "$ID" --yes

失敗した送信を見つけ、そのうち 1 つに何が起きたかを読みます。--json なしでパイプすると、--all は 1 行に 1 つの JSON オブジェクトを出力します。

openemail emails list --status failed,partial --from [email protected] --all | jq -r .idopenemail emails get msg_3f9a1c07d2b84e6a9c5b1f20openemail emails list-events msg_3f9a1c07d2b84e6a9c5b1f20 --all --json | jq -r '.items[] | .createdAt + " " + .type'

UTC+2 の午前 0 時で区切った日単位で 1 週間分のエンゲージメントを読み、誰も開封しなかったものを一覧にし、1 通のメッセージの各リンクのクリック数を数えます。

openemail tracking get-stats --days 7 --offset-minutes 120 --json | jq '{ tracked, openRate, clickRate }'openemail tracking list --no-opened --days 7 --all | jq -r .subjectopenemail tracking list-clicks msg_3f9a1c07d2b84e6a9c5b1f20 --all | jq -r .url | sort | uniq -c

• —ブラウザでのサインインでは承認ページでスコープを求め、openemail login --scopes emails:send,emails:read で両方をあらかじめ選択できます。スコープが足りないコマンドは終了コード 4 と insufficient_scope で停止し、そのスコープ名を示します。
• —5 MB を超えるファイルを付けた send --attach は、まずそれらを「ファイル」にアップロードするため、files:write も必要です。
• —これらのコマンドはどれも確認コードを求めないので、ブラウザでのサインインでも API キーと同じように実行されます。
• —emails cancel は取り消す前に確認し、--yes を付けると代わりに答えます。--yes なしの無人実行では、Refusing to run unattended. Pass --yes to confirm. と終了コード 2 で停止します。
• —emails send、send-batch、reschedule は何も尋ねません。send は概要を表示し、ターミナルでのみ確認を求めます。--yes を付けるとそれも省略されます。
• —--dry-run はコマンドが送るはずのリクエストを表示し、何も送らずに終了コード 0 で終了します。emails translate では AI アクションを消費せず、emails cancel では何も尋ねません。

emails list、emails list-events、tracking list、list-opens、list-clicks は 1 ページを読みます。--limit でそのサイズを指定します。2 つの emails のリストでは 1 から 100 で既定は 25、3 つの tracking のリストでは 1 から 200 で既定は 50 です。--cursor は、ページが表示したカーソルから続けます。

• —--all はすべてのページを読んで項目をストリームします。ターミナルでは表として、パイプしたときや --ndjson を付けたときは 1 行に 1 つの JSON オブジェクトとして出力します。
• —--max <n> はその件数で停止し、--all を含意します。
• —--json は、--all の場合も含めて 1 つの { items, hasMore, nextCursor } ドキュメントを出力します。
• —ページングはオフセットではなくカーソルで行うので、ページをめくっている間に送信されたメールによって行がずれたり重複したりすることはありません。

• —実行のたびに独自の冪等キーが作られ、その実行内の再試行をカバーします。送信を 2 回実行すると、両方の実行で同じ --idempotency-key を渡さない限り 2 回送信されます。同じキーで異なる本文を送ると、idempotency_key_reuse と終了コード 7 で拒否されます。
• —取り消しや日時の移動ができるのは queued と scheduled のメールだけです。取り消し猶予のない即時送信はリクエストの中で送られるため、ID を手にした時点では通常もう手遅れで、呼び出しは email_not_cancellable と終了コード 6 で終わります。
• —取り消したメールは取り消されたままです。再スケジュールで変わるのは時刻だけで、期間で指定した場合はサーバーがリクエストを受け取った時点から数えます。本文を変えるには、取り消してから送り直してください。
• —翻訳を生成できない場合は送信全体が拒否され、未翻訳のまま送られるものはありません。翻訳付きの一括送信に含められる translate 付きのメッセージは最大 10 通です。
• —送信枠を使い切ると、月の初日まで送信が send_quota_exceeded で止まり、AI の枠を使い切ると、UTC の午前 0 時まで翻訳が ai_quota_exceeded で止まります。どちらも終了コード 8 です。
• —oe_test_ キーで送ったメールは配信されません。ステータスは sent と表示され、transport は test になり、追跡されることもありません。
• —ピクセルも書き換えられたリンクも含まないメッセージに対して、emails get-tracking と tracking get は 404（終了コード 5）を返します。追跡されていないことは、開封されていないことと同じではないからです。トラッキングはメッセージ送信時の設定に従うため、後でオンにしても以前のメールには及びません。
• —どの数値も下限値です。メールクライアントが画像をブロックしている読者は開封として数えられず、クリックは開封よりも強い既読の証拠です。
• —list-opens と list-clicks は、何も追跡されていない msg_ の ID には 404 を返しますが、tmsg_ の ID は与えられたまま受け取るため、不明な ID では空のリストが返ります。
• —一部のアドレスに限定されたキーは、それらのアドレスから送られたメールしか見えず、ドメイン全体を持つキーはそのドメインのすべてのアドレスを対象にします。

このページでは特に重要なフラグを紹介しています。openemail <command> --help は、コマンドが受け取るすべての引数とフラグを、その型、必要なスコープ、メソッドとパス、返す内容、API リファレンスの注記とともに一覧表示します。--json を付けると、同じヘルプを 1 つの JSON ドキュメントとして出力します。

openemail emails --helpopenemail emails send --helpopenemail tracking list-opens --help --json