予約とキャンセル
`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' => new \DateTimeImmutable('2027-01-01 09:00', new \DateTimeZone('UTC'))]);$client->emails->send([...$message, 'scheduledAt' => '2027-01-01T09:00:00.000Z']);DateTimeInterface、文字列の ISO 8601 時刻、または PT1H や P2D のような期間。1 年先まで指定でき、過去は指定できません。前に作ったメッセージを scheduledAt と並べて新しい配列に展開すると、元のメッセージはそのままでこのフィールドが追加されます。
DateTimeInterface は、どのタイムゾーンで作られたかに関係なく UTC の時刻として送られるため、Europe/London の 09:00 はそれが指す時刻として送られます。2027-01-01 のような時刻のない日付文字列は、その日の UTC 午前 0 時として読まれるため、時刻が重要なときは時刻まで含めて渡してください。
移動と停止
$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'], new \DateTimeImmutable('+1 day'));$client->emails->cancel($queued['id']);止められるのは queued と scheduled のメッセージだけです。それより先に進んだものは、一部がすでに誰かのメールボックスにあるため、ConflictException をスローします。キャンセル済みのメッセージをキャンセルしても成功し、何も変わりません。
ある期間に送信待ちのものを探すには、アプリのカレンダーと同じように、status: ['scheduled', 'queued'] と scheduledFrom:、scheduledTo: を指定して一覧を取得します。
送信前に変更する
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' => new \DateTimeImmutable('2026-10-05 08:00', new \DateTimeZone('UTC')),]); echo $updated['status'], ' ', $updated['subject'], ' ', $updated['scheduledAt'], PHP_EOL;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]); echo $held['status'], ' ', $held['cancellableUntil'], PHP_EOL;予約されたメッセージは送信されるまですでに取り消せるので、この 2 つは併用できず、サーバーが拒否します。即時メッセージの送信取り消し猶予には、こちらを使ってください。
パラメーター: 予約
scheduledAtDateTimeInterface or string- `emails->send` での送信時刻：`DateTimeInterface`、文字列の ISO 8601 時刻、または `PT1H` や `P2D` のような期間。`DateTimeInterface` は UTC の時刻として、文字列はそのまま送られ、時刻のない日付文字列は UTC 午前 0 時を意味します。少なくとも 1 秒先、最大 365 日先までで、どちらの境界を外れても `scheduledAt` に対する `validation_error` になります。自然言語は受け付けません。「来週の火曜日」を誤って解釈すると、取り消せない時刻にメッセージが送られてしまうからです。
cancellableForSecondsint- 「即時」送信に付ける送信取り消しの猶予：0〜900 の int で、既定値は 0 です。0 より大きい値を `scheduledAt` と一緒に指定すると拒否されます。スケジュールされた送信は、送られるまですでにキャンセルできるからです。この方法で保留されたメッセージは `scheduled` ではなく `queued` になります。短い遅延を付けた、同じ保留の仕組みです。
$idstring必須- `msg_` の id で、`emails->cancel`、`emails->reschedule`、`emails->update` の第 1 引数です。これらは専用のスコープではなく `emails:send` を必要とし、キー自身のワークスペースの中で id を探すため、別のワークスペースに属する id は、存在しなかった id とまったく同じく `not_found_error` になります。
$scheduledAtDateTimeInterface or string必須- 新しい時刻で、`emails->reschedule` の第 2 引数です。同じ規則で読まれ、同じ 1 年の範囲が適用されます。`reschedule` が変更するのはこれだけで、クライアントはほかに何も送りません。期間は「サーバー」が読んだ時点を基準とするため、リトライされた再スケジュールは、1 回目が成功した場合よりわずかに遅い時刻になります。遅くなることはあっても、早くなることはありません。
apiKeystring- 3 つの呼び出しのいずれでも使える名前付き引数です。クライアントのキーではなくこのキーで実行します。
レスポンス
cancel、reschedule、update はいずれも、メッセージ全体を API の camelCase の名前をキーとする配列として返します。
objectstring- 常に `email`。これらの呼び出しは受領の確認ではなくメッセージ全体を返すため、何が変わったかを見るために改めて取得する必要はありません。`emails->send` はこれと同じ形に `replayed` を加えたものを返します。
idstring- `msg_` のハンドル。メッセージが存在する限り変わらず、そのメッセージに対する他のすべての呼び出しが受け取る id です。
statusstring- キャンセル後は `cancelled`、再スケジュール後は `scheduled` です。取り消し猶予の後ろで `queued` だっただけのメッセージも同様で、再スケジュールによって本当のスケジュールになります。移動や停止ができるのは `queued` と `scheduled` のメッセージだけです。それより先に進んだものは、一部がすでに誰かのメールボックスにあるため、`errorCode` が `email_not_cancellable` の `ConflictException` をスローします。
scheduledAtstring or null- メッセージが送り出される予定の ISO 8601 時刻。取り消し猶予にも `scheduledAt` の送信にも設定されます。この 2 つは同じ仕組みだからです。通常の即時送信では null です。
cancellableUntilstring or null- キャンセルできなくなる時刻で、保留されるどちらの経路でも `scheduledAt` と同じ時刻です。即時送信では null で、呼び出しが戻る時点ですでに送られています。
sentAtstring or null- メッセージが実際に送り出された時刻。待機中は null で、キャンセルされたメッセージではずっと null のままです。
messageIdstring or null- RFC 5322 の Message-ID。MIME ができるまでは null なので、これらの呼び出しが対象にできるメッセージでは常に null です。API でメッセージを指定するためのものではなく、後でバウンスが返ってくるときの手がかりでもありません。送信サービスが送り出すときにこのヘッダーを書き換えるからです。
threadIdstring or null- このメッセージが属するスレッド。リクエストから取られ、送信後はトランスポートが報告する値で書き換えられます。返信でない場合は null です。
transportstring or null- バイト列がどの経路で送り出されたか。配送されるまでは null なので、キャンセルや再スケジュールが返し得るメッセージでは常に null です。テストモードの送信は `test` を記録します。このパッケージがまだ名前を知らないトランスポートが現れることもあるため、未知の値はエラーではなく情報として扱ってください。
attemptsint- 配送処理がこの行を確保した回数。送信の成功ではなく確保のたびに増え、まだ待機中のものでは 0 です。
lastErrorstring or null- メッセージに記録された最後の失敗で、何も失敗していない間は null です。ジョブをキューに入れられなかった保留中の送信は、ここに `Could not schedule: …` と書かれて `failed` に移ります。誰も求めていないのにスケジュール済みのメッセージがキャンセルできなくなるのは、この場合だけです。
fromstring- メッセージの送信元として認められたアドレス：送られた `from` を、素のアドレスにして小文字で保存したものです。`emails->list` の `from:` フィルターは完全一致で比較するため、表示名はここでは捨てられます。