テンプレートで送信する
保存された本文がメッセージを供給し、リクエストがエンベロープと値を供給します。
実際の呼び出しを、ご自身のキーで自分のワークスペースに対して実行します。
POST /templates/{id}/send
保存された本文がメッセージを供給し、リクエストがエンベロープと値を供給します。
例
templates:write と emails:send の両方が必要です。Idempotency-Key は POST /emails とまったく同じように扱われます。
curl -X POST "$OE/templates/order-shipped/send" -H "$AUTH" \ -H "Content-Type: application/json" -H "Idempotency-Key: order:AC-4192:shipped" \ -d '{ "from": "Acme Dispatch <[email protected]>", "to": ["[email protected]"], "version": 5, "props": { "orderId": "AC-4192", "customer": "Ada" } }'{ "object": "email", "id": "msg_c5f21cc6…", "status": "queued", "from": "[email protected]", "subject": "Order AC-4192 is on its way", "template": { "id": "order-shipped", "version": 5 }}両方のスコープが必要で、どちらも冗長ではありません。呼び出し側が保存された本文に触れるので templates:write、メールがワークスペースの外へ出るので emails:send です。自分の本文を送ってよいキーでも、他人のテンプレートを送ることはできません。
自動化されたものの中では version を固定してください。省略するとその時点で公開されているものが解決されます。文面を他人が所有しているときはそれが望ましく、その人が書き直した朝には望ましくありません。
subject はこのメッセージに限ってテンプレート自身の件名を上書きします。cancellableForSeconds、tracking、tags は通常の送信とまったく同じように振る舞います。
POST /emails にも同じことをする template フィールドがあり、すでにそちらでメッセージを組み立てている呼び出し側のためのものです。このエンドポイントが存在するのは、保存された本文に触れるために、自分が作文していないメッセージの形を用意しなくて済むようにするためです。
送信が拒否される場合
props は提案ではなく契約であり、以下の失敗はすべて何かが送出される前に起こります。代わりの結末、つまり注文番号のあるべき場所が空白のままメールが出ていくことは、何からも報告されず、取り消すこともできません。
| コード | ステータス | 何が起きたか |
|---|---|---|
| `resource_not_found` | 404 | この接続には、その id または slug を持つテンプレートがありません。 |
| `template_not_published` | 422 | テンプレートは存在するが一度も公開されていないか、指定したバージョンがまだ下書きです。 |
| `template_version_not_found` | 422 | このテンプレートが持ったことのない version を固定しました。 |
| `missing_template_prop` | 422 | required と宣言された prop が、欠けているか null か空でした。 |
| `unknown_template_prop` | 422 | そのバージョンが宣言していないキーを渡しました。メッセージには宣言済みのキーが列挙されます。 |
| `unknown_template_slot` | 422 | 同じことがスロットについて起きた場合です。 |
| `invalid_template_prop` | 422 | string でも number でも boolean でもない値です。object や array を HTML に差し込むことはできません。 |
これらの param は template.props.<key> なので、クライアントはメッセージをパースしなくても、間違えたフィールドを指し示せます。