下書き
`drafts->list`、`listAll`、`iterate`、`get`、`create`、`update`、`delete`。
すべてのメソッド
$page = $client->drafts->list(query: 'invoice', limit: 25);$draft = $client->drafts->get('draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8');echo count($page), ' ', $draft['subject'], PHP_EOL; $created = $client->drafts->create([ 'to' => ['[email protected]'], 'cc' => [], 'bcc' => [], 'subject' => 'Your September invoice', 'html' => '<p>Draft body.</p>', 'from' => '[email protected]', 'threadId' => 'CAHk7pQ2x9LmZ4-mail.example.com',]); $updated = $client->drafts->update($created['id'], ['subject' => 'Revised']);$client->drafts->delete($updated['id']);update は下書きの id を保持するため、返される値は常に渡した id です。不明な id は新しい下書きにはならず、NotFoundException としてスローされる 404 になります。
下書きのフィールドは API の名前どおりのキーを持つ 1 つの配列なので、下書きが返信するスレッドは threadId です。下書きは camelCase のキーを持つ配列として返るため、$draft['subject'] で件名を読めます。書き込みはどれも object と id だけを返すため、下書き全体は get で読んでください。
list は threads->list と同じようにページ分割します。API の pageToken は nextCursor として返り、cursor: として渡し、listAll と iterate はそれを自動的にたどります。iterate は下書きを 1 つずつ yield する Generator を返します。1 ページには 25 件の下書きが入り、limit: で最大 100 件まで指定できます。query: は threads->list の検索構文を受け付け、検索が下書きの外に及ぶことはありません。行は object と id だけなので、受信者、件名、本文を得るには get を呼び出してください。
下書きの一覧は hasMore を示さないため、カーソルが返ったときは常に hasMore が true です。サーバーはページが満杯のときは必ずカーソルを出すため、たまたま満杯だった最後のページの後には空のページが 1 つ続きます。
下書きは DRAFT ラベルの付いたスレッドとして保存されるため、$client->threads->list(folder: 'draft') でも同じ下書きが一覧になります。通常のスレッドの id は threads->get なら開けますが、get、update、delete には 404 が返ります。delete は下書きを完全に削除します。ごみ箱には移らず、元に戻すこともできません。
下書きを送信するには、その id を draftId として emails->send に渡します。内容は下書きから、エンベロープは送信の呼び出しから取られます。下書きは template や translate とは組み合わせられません。
$client->emails->send([ 'from' => '[email protected]', 'to' => '[email protected]', 'draftId' => 'draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8',]);パラメーター：drafts->create と drafts->update
toarray- 受信者のアドレスを文字列のリストで指定します。`emails->send` が受け付ける配列の形式は使えません。このエンドポイントはリストを、ドライバーが求めるカンマ区切りのリストに結合するからです。文字列には `Ada Lovelace <[email protected]>` のように表示名を含められますが、カンマを含む名前は 2 つの壊れた受信者に分かれてしまいます。`emails->send` と違い、ここではクライアントが単独の文字列をリストに包まないため、`['[email protected]']` のように渡してください。作成時にリストを省略すると空として保存されます。更新時にフィールドを省略すると、保存済みの受信者はそのまま残ります。ハンドラーが先に下書きを読んでからマージするからです。
ccarray- Cc のアドレスで、`to` と同じ形式です。省略すると、作成時は空になり、更新時は変更されません。
bccarray- Bcc のアドレスで、`to` と同じ形式です。省略すると、作成時は空になり、更新時は変更されません。
subjectstring- 下書きの件名で、最大 998 文字（RFC 5322 の行の上限）。作成時の既定値は空文字列で、空の件名は `(no subject)` として保存されるため、下書きには必ず件名があります。
htmlstring- マークアップで書いた下書きの本文で、最大 1,000,000 文字。こちらが優先される本文です。`html` と `text` はドライバーの 1 つのメッセージフィールドに入るため、両方を送るとこちらが保存されます。
textstring- プレーンテキストの本文で、最大 1,000,000 文字。`html` がない場合にだけ使われます。下書きは 2 つの部分ではなく 1 つの本文を保存するため、ここで指定したテキストは、下書きを読むときに変換されないまま `html` として返ります。
fromstring or null- 下書きに保存する送信者のアドレスで、表示名は付けても付けなくてもかまいません。作成時に省略すると、下書きには送信者がありません。更新時に省略すると、保存済みの下書きから引き継がれます。ドライバーは渡されたものからメッセージ全体を作り直すため、これを落とした部分的な更新では、選んだ送信者が黙って変わってしまうからです。更新時に空文字列または null を渡すと消去されます。
threadIdstring- 下書きを既存のスレッドに結びつけ、返信として保存します。`from` と同じく、更新時に省略すると引き継がれます。これなしでメッセージを作り直すと、返信がスレッドから切り離されてしまうからです。更新時に空文字列を渡すと切り離されます。下書きは引き続き独自の id を持つ独立したスレッドとして保存されるため、返信先のスレッドの中ではなく、下書きと一緒に一覧に表示されます。
値を保持するにはフィールドを省略してください。null を渡すのは同じではありません。クライアントはそれを送信し、更新時の from（null で送信者を消去します）を除くすべてのフィールドが 422 invalid_parameter で拒否します。省略可能な値の配列は、渡す前に array_filter($fields, static fn(mixed $value): bool => $value !== null) を通してください。ボディも厳密です。この 8 つ以外のフィールドも同じように拒否され、添付ファイル用のフィールドはありません。
レスポンス：下書き（drafts->get）
objectstring- 常に `draft` です。
idstring- 下書きの id で、`draft-` の後に UUID が続きます。書き込みは下書き全体ではなく `object` と `id` だけを返すため、送った id を使い回すのではなく、結果から id を読み取ってください。
toarray- 下書きが保存したとおりの受信者のアドレスで、表示名を除いた素のアドレスです。下書きに受信者がない場合は null ではなく空のリストです。
ccarray- 保存されたとおりの Cc のアドレス。下書きにない場合は null ではなく空のリストです。
bccarray- 保存されたとおりの Bcc のアドレス。下書きにない場合は null ではなく空のリストです。
subjectstring- 保存された件名で、null にはなりません。件名なしで保存された下書きは、メールボックスが保存するプレースホルダーの `(no subject)` になるため、空文字列かどうかではなく、それと比較してください。
htmlstring- 保存された本文で、下書きに本文がない場合は空文字列です。返すときに別のテキストのフィールドはないため、`text` だけで保存された下書きもここに返ります。
fromstring or null- 下書きが保存されたときのアドレスで、ワークスペースがまだそのアドレスから送信できる間だけ報告されます。送信者なしで保存された下書きや、その後なくなったアドレスで保存された下書きでは null です。
threadIdstring or null- 下書きが返信するスレッドで、新しい会話を始める下書きでは null です。
attachmentsarray- 各エントリは `filename` と `contentType` だけを持ちます。下書きの添付ファイルは、内容なしで名前と種類だけが保存されるからです。`update` を行うとこのリストは空になります。