メールを送信する

$email = $client->emails->send([    'from' => ['email' => '[email protected]', 'name' => 'Acme Billing'],    'to' => ['[email protected]', 'Grace <[email protected]>'],    'cc' => '[email protected]',    'bcc' => [['email' => '[email protected]']],    'replyTo' => '[email protected]',    'subject' => 'Your September invoice',    'html' => '<p>Invoice attached.</p>',    'text' => 'Invoice attached.',    'headers' => ['X-Campaign' => 'invoices'],    'attachments' => [['filename' => 'invoice.pdf', 'content' => new \SplFileInfo('invoice.pdf')]],    'threadId' => 'CAHk7pQ2x9LmZ4-mail.example.com',    'scheduledAt' => 'PT1H',    'tags' => ['order' => '4021'],    'tracking' => ['opens' => true, 'clicks' => true],]); echo $email['id'], ' ', $email['status'], PHP_EOL;

to、cc、bcc は受信者 1 人、または受信者のリストを受け取り、1 人だけの場合は自動的にリストに包まれます。それぞれ素のアドレス、Name <addr@host>、または email と name を持つ配列のいずれかです。

メッセージは API のフィールド名をキーとする 1 つの配列です。そのため replyTo と scheduledAt は camelCase のままです。一方 idempotencyKey: と apiKey: は呼び出しの名前付き引数で、メッセージの一部にはなりません。前に作ったメッセージのフィールドを 1 つだけ変えるには、新しい配列に展開します。$client->emails->send([...$message, 'subject' => 'Re: your invoice']) は他のフィールドをすべて保ったまま件名を置き換えます。

API の camelCase の名前をキーとする配列なので、$email['status'] でステータスを読めます。

translate は、メッセージが出ていく前にそれを別の人の言語で書き直します。本文と、無効にしない限り件名が、API がリクエストを受け付けた時点で翻訳され、その出力がそのまま送られます。翻訳を生成できなかった場合は、あなたが書いた言語のまま投函するのではなく送信を拒否します。

$email = $client->emails->send([    'from' => '[email protected]',    'to' => '[email protected]',    'subject' => 'Your September invoice',    'html' => '<p>Invoice attached. Payment is due on the 14th.</p>',    'translate' => ['to' => 'de'],]); print_r($email['translation'] ?? []);

このとき $email['translation'] は、language が de、languageName が German、detectedSourceLanguage が en で、subject と includeOriginal はどちらも true です。

それは送られる前に誰も読んでいません。emails->translate は同じ往復を 1 段階手前で止めたものです。結果を人に見せて修正してもらい、承認されたものを、呼び出しに translate を一切付けずに送信してください。もう一度渡すと 2 回目の翻訳が行われ、修正が捨てられてしまいます。

$preview = $client->emails->translate([    'subject' => 'Your September invoice',    'html' => '<p>Invoice attached. Payment is due on the 14th.</p>',    'to' => 'de',]); echo $preview['language']['native'], PHP_EOL, $preview['subject'], PHP_EOL, $preview['html'], PHP_EOL;echo 'Send it as it is? [y/N] '; $answer = fgets(STDIN); if ($answer !== false && strtolower(trim($answer)) === 'y') {    $client->emails->send([        'from' => '[email protected]',        'to' => '[email protected]',        'subject' => $preview['subject'],        'html' => $preview['html'],    ]);}

use OpenEmail\Constants\Languages;use OpenEmail\OpenEmail; echo count(Languages::ALL), PHP_EOL; $current = $client->languages->list();echo count($current), PHP_EOL; echo OpenEmail::resolveLanguage('Deutsch')['code'] ?? 'none', PHP_EOL;echo OpenEmail::resolveLanguage('zh-TW')['code'] ?? 'none', PHP_EOL;echo OpenEmail::languageByCode('DE')['native'] ?? 'none', PHP_EOL;var_dump(OpenEmail::isRtlLanguage('ar'));

これらの行は、このバージョンに同梱されている行数の 200、API が現在持つ行数、続いて de、zh-Hant、Deutsch、bool(true) を出力します。この表は OpenEmail\Constants\Languages::ALL として、ピッカーの表示順で同梱されています。code、label、native、flag、rtl を持つ配列のリストなので、最初のリクエストの前にピッカーを埋められます。languages->list は同じ行を通信で取得し、通常のリストとして返します。このバージョンに同梱された行ではなく現在の行を使いたい呼び出し元向けです。OpenEmail::resolveLanguage() はコード、英語名、その言語自身での名前、または別名（zh-TW はもう一覧にないコードの別名です）を受け取り、一致するものがなければ null を返します。OpenEmail::languageByCode() は大文字小文字を問わずコードの完全一致で照合し、OpenEmail::isRtlLanguage() は言語が右から左に書かれるかどうかを返します。16 の行がそうした言語です。native、label、code をまとめて検索し、native を先に表示し、コードを保存してください。

• —API が照合できない言語は、何かが送信される前に translate.to に対する validation_error になります。
• —30,000 文字を超えると translation_too_long、インストールに AI が設定されていなければ translation_not_configured、ワークスペースが当日の AI 操作を使い切っていれば 429 ai_quota_exceeded（UTC の午前 0 時にリセットされ、リトライはされません）、プロバイダーが応答しなければ translation_failed になります。いずれの場合も、代わりに未翻訳のメッセージが送られることはありません。
• —template と併用できます。翻訳されるのはレンダリング後の出力なので、保存された 1 つの本文が、顧客が読むすべての言語に対応できます。文書全体をレンダリングするテンプレートは、doctype、<style> ブロック、@font-face 規則を保ちます。モデルへ渡されるのは body だけで、残りは後から周りに戻されます。<title> はそのままで、どのみち何も表示しません。
• —再試行に追加費用はかかりません。翻訳は冪等性のフィンガープリントの一部ではなく（リクエストは translate を含めて一部です）、応答のなかった送信を同じ Idempotency-Key で再試行すると、翻訳して 2 通目を送るのではなく、すでに存在するメッセージを再生します。
• —queued または scheduled の翻訳済みメッセージは、承認された文面を保持します。emails->reschedule で時刻を動かすことはできますが、emails->update は新しい文面を 409 translation_locked で拒否するため、内容を変えるにはキャンセルして送り直すことになります。

content は通信上では base64 です。クライアントが読めるものを渡せば、バイト列は自動的にエンコードされます。fopen のストリームリソース、SplFileInfo、または PSR-7 のストリームかアップロードされたファイルを渡せます。文字列はそのまま送られるため、あらかじめ base64 になっている必要があります。メモリ上のバイト列は OpenEmail::toBase64() で base64 にできます。

use OpenEmail\OpenEmail; $attachments = [    ['filename' => 'invoice.pdf', 'content' => OpenEmail::toBase64(file_get_contents('invoice.pdf')), 'contentType' => 'application/pdf'],    ['filename' => 'report.csv', 'content' => new \SplFileInfo('report.csv')],    ['filename' => 'contacts.csv', 'content' => fopen('contacts.csv', 'rb')],    ['fileId' => 'file_6bb640f5b99e47deb758f1f5'],]; $client->emails->send([    'from' => '[email protected]',    'to' => '[email protected]',    'subject' => 'Your documents',    'text' => 'All three are attached.',    'attachments' => $attachments,]);