メールを送信する

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: Pathname("invoice.pdf")}],  threadId: "CAHk7pQ2x9LmZ4-mail.example.com",  scheduledAt: "PT1H",  tags: {order: "4021"},  tracking: {opens: true, clicks: true}) puts email[:id], email[:status]

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

メッセージはキーワード引数か、1 つの Hash として渡します。Hash と並べて渡したキーワード引数はその Hash にマージされ、同じフィールドを指定した場合はキーワード引数が優先されるため、client.emails.send(message, subject: "Re: your invoice") は前に作ったメッセージのフィールドを 1 つだけ変更します。キーは API の名前をそのまま使うので、replyTo と scheduledAt は camelCase のままです。一方 idempotency_key: と api_key: は呼び出しのオプションで、メッセージの一部にはなりません。

Symbol キーの Hash なので、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"}) p email[:translation]

このとき email[:translation] は {language: "de", languageName: "German", detectedSourceLanguage: "en", subject: true, 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") puts preview.dig(:language, :native), preview[:subject], preview[:html]print "Send it as it is? [y/N] " if $stdin.gets.to_s.strip.casecmp?("y")  client.emails.send(    from: "[email protected]",    to: "[email protected]",    subject: preview[:subject],    html: preview[:html]  )end

p OpenEmail::LANGUAGES.size current = client.languages.listp current.size p OpenEmail.resolve_language("Deutsch")&.fetch(:code)p OpenEmail.resolve_language("zh-TW")&.fetch(:code)p OpenEmail.language_by_code("DE")&.fetch(:native)p OpenEmail.rtl_language?("ar")

これらの行は、このバージョンに同梱されている行数の 200、API が現在持つ行数、続いて "de"、"zh-Hant"、"Deutsch"、true を出力します。この表は OpenEmail::LANGUAGES として、ピッカーの表示順で同梱されています。code、label、native、flag、rtl を持つ Hash の凍結された Array なので、最初のリクエストの前にピッカーを埋められます。languages.list は同じ行を通信で取得し、素の Array として返します。このバージョンに同梱された行ではなく現在の行を使いたい呼び出し元向けです。OpenEmail.resolve_language はコード、英語名、その言語自身での名前、または別名（zh-TW はもう一覧にないコードの別名です）を受け取り、一致するものがなければ nil を返します。OpenEmail.language_by_code は大文字小文字を問わずコードの完全一致で照合し、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 です。バイト列を渡せば自動的にエンコードされます。File.binread が返すようなバイナリの String、開いた File のような IO、または読み込みを任せられる Pathname を渡せます。

attachments = [  {filename: "invoice.pdf", content: File.binread("invoice.pdf"), contentType: "application/pdf"},  {filename: "report.pdf", content: Pathname("report.pdf")},  {fileId: "file_6bb640f5b99e47deb758f1f5"}] client.emails.send(  from: "[email protected]",  to: "[email protected]",  subject: "Your documents",  text: "Both are attached.",  attachments:)