予約とキャンセル
`scheduledAt`、`emails.reschedule`、`emails.update`、`emails.cancel`。
あとで送る
message = {from: "[email protected]", to: "[email protected]", subject: "Your September invoice", text: "Invoice attached."} client.emails.send(message, scheduledAt: "PT1H")client.emails.send(message, scheduledAt: Time.utc(2027, 1, 1, 9))client.emails.send(message, scheduledAt: "2027-01-01T09:00:00.000Z")Time または DateTime、String の ISO 8601 時刻、または PT1H や P2D のような期間。1 年先まで指定でき、過去は指定できません。Hash と並べたキーワード引数で、前に作ったメッセージにこのフィールドを追加できます。
Ruby の Date は 2027-01-01 のような日付だけの値として送られ、API はそれをその日の UTC 午前 0 時として読みます。時刻が重要なときは Time.utc(2027, 1, 1, 9) のような Time を渡してください。
移動と停止
message = {from: "[email protected]", to: "[email protected]", subject: "Your September invoice", text: "Invoice attached."} queued = client.emails.send(message, scheduledAt: "PT1H") client.emails.reschedule(queued[:id], Time.now + 86_400)client.emails.cancel(queued[:id])止められるのは queued と scheduled のメッセージだけです。それより先に進んだものは、一部がすでに誰かのメールボックスにあるため、OpenEmail::ConflictError を送出します。キャンセル済みのメッセージをキャンセルしても成功し、何も変わりません。
ある期間に送信待ちのものを探すには、アプリのカレンダーと同じように、status: ["scheduled", "queued"] と scheduled_from:、scheduled_to: を指定して一覧を取得します。
送信前に変更する
emails.update はまだ送られていないメッセージを変更します。いつ送るかは scheduledAt で、何を書くかは subject、html、text で、どのアドレスから送るかは from で、誰に送るかは to、cc、bcc で指定します。どれを組み合わせて送ってもよく、省略したフィールドは値を保持します。受信者のリストは保存されているリストを丸ごと置き換えます。アプリのカレンダーでスケジュール済みのメッセージを編集するときに行われるのがこれです。
updated = client.emails.update( "msg_3f9a1c07d2b84e6a9c5b1f20", subject: "Your September invoice, corrected", to: ["[email protected]", "[email protected]"], scheduledAt: Time.utc(2026, 10, 5, 8)) puts updated[:status], updated[:subject], updated[:scheduledAt]from は送信時と同じようにチェックされるため、キーが送信元として使えるアドレスでなければなりません。受け付け時に翻訳されたメッセージは承認された文面を保持するため、新しい subject、html、text を指定すると 409 translation_locked になります。スケジュール前に暗号化されたメッセージは、文面と受信者を保持します。これらはキャンセルして送り直してください。
代わりに取り消し猶予を使う
message = {from: "[email protected]", to: "[email protected]", subject: "Your September invoice", text: "Invoice attached."} held = client.emails.send(message, cancellableForSeconds: 30) puts held[:status], held[:cancellableUntil]予約されたメッセージは送信されるまですでに取り消せるので、この 2 つは併用できず、サーバーが拒否します。即時メッセージの送信取り消し猶予には、こちらを使ってください。
パラメーター: 予約
scheduledAtTime, DateTime or String- `emails.send` での送信時刻：Time または DateTime、String の ISO 8601 時刻、または `PT1H` や `P2D` のような期間。Time と DateTime は UTC の時刻として、String はそのまま、Ruby の Date はその日の UTC 午前 0 時を意味する日付だけの値として送られます。少なくとも 1 秒先、最大 365 日先までで、どちらの境界を外れても `scheduledAt` に対する `validation_error` になります。自然言語は受け付けません。「来週の火曜日」を誤って解釈すると、取り消せない時刻にメッセージが送られてしまうからです。
cancellableForSecondsInteger- 「即時」送信に付ける送信取り消しの猶予：0〜900 の Integer で、既定値は 0 です。0 より大きい値を `scheduledAt` と一緒に指定すると拒否されます。スケジュールされた送信は、送られるまですでにキャンセルできるからです。この方法で保留されたメッセージは `scheduled` ではなく `queued` になります。短い遅延を付けた、同じ保留の仕組みです。
idString必須- `msg_` の id で、`emails.cancel`、`emails.reschedule`、`emails.update` の第 1 引数です。これらは専用のスコープではなく `emails:send` を必要とし、キー自身のワークスペースの中で id を探すため、別のワークスペースに属する id は、存在しなかった id とまったく同じく `not_found_error` になります。
scheduled_atTime, DateTime or String必須- 新しい時刻で、`emails.reschedule` の第 2 引数です。同じ規則で読まれ、同じ 1 年の範囲が適用されます。`reschedule` が変更するのはこれだけで、クライアントはほかに何も送りません。期間は「サーバー」が読んだ時点を基準とするため、リトライされた再スケジュールは、1 回目が成功した場合よりわずかに遅い時刻になります。遅くなることはあっても、早くなることはありません。
api_keyString- 3 つの呼び出しのいずれでも、クライアントのキーではなくこのキーで実行します。
レスポンス
cancel、reschedule、update はいずれも、メッセージ全体を Symbol キーの Hash として返します。
objectString- 常に `email`。これらの呼び出しは受領の確認ではなくメッセージ全体を返すため、何が変わったかを見るために改めて取得する必要はありません。`emails.send` はこれと同じ形に `replayed` を加えたものを返します。
idString- `msg_` のハンドル。メッセージが存在する限り変わらず、そのメッセージに対する他のすべての呼び出しが受け取る id です。
statusString- キャンセル後は `cancelled`、再スケジュール後は `scheduled` です。取り消し猶予の後ろで `queued` だっただけのメッセージも同様で、再スケジュールによって本当のスケジュールになります。移動や停止ができるのは `queued` と `scheduled` のメッセージだけです。それより先に進んだものは、一部がすでに誰かのメールボックスにあるため、コード `email_not_cancellable` の `conflict_error` になります。
scheduledAtString or nil- メッセージが送り出される予定の ISO 8601 時刻。取り消し猶予にも `scheduledAt` の送信にも設定されます。この 2 つは同じ仕組みだからです。通常の即時送信では nil です。
cancellableUntilString or nil- キャンセルできなくなる時刻で、保留されるどちらの経路でも `scheduledAt` と同じ時刻です。即時送信では nil で、呼び出しが戻る時点ですでに送られています。
sentAtString or nil- メッセージが実際に送り出された時刻。待機中は nil で、キャンセルされたメッセージではずっと nil のままです。
messageIdString or nil- RFC 5322 の Message-ID。MIME ができるまでは nil なので、これらの呼び出しが対象にできるメッセージでは常に nil です。API でメッセージを指定するためのものではなく、後でバウンスが返ってくるときの手がかりでもありません。送信サービスが送り出すときにこのヘッダーを書き換えるからです。
threadIdString or nil- このメッセージが属するスレッド。リクエストから取られ、送信後はトランスポートが報告する値で書き換えられます。返信でない場合は nil です。
transportString or nil- バイト列がどの経路で送り出されたか。配送されるまでは nil なので、キャンセルや再スケジュールが返し得るメッセージでは常に nil です。テストモードの送信は `test` を記録します。この gem がまだ名前を知らないトランスポートが現れることもあるため、未知の値はエラーではなく情報として扱ってください。
attemptsInteger- 配送処理がこの行を確保した回数。送信の成功ではなく確保のたびに増え、まだ待機中のものでは 0 です。
lastErrorString or nil- メッセージに記録された最後の失敗で、何も失敗していない間は nil です。ジョブをキューに入れられなかった保留中の送信は、ここに `Could not schedule: …` と書かれて `failed` に移ります。誰も求めていないのにスケジュール済みのメッセージがキャンセルできなくなるのは、この場合だけです。
fromString- メッセージの送信元として認められたアドレス：送られた `from` を、素のアドレスにして小文字で保存したものです。`emails.list` の `from:` フィルターは完全一致で比較するため、表示名はここでは捨てられます。