designing-email-templates

メールテンプレートのデザイン

PostHog のワークフロー用メールテンプレートを作成または編集するときに、このスキルを使用してください。ブロードキャストキャンペーンと function_email ワークフローアクションでは、レンダリング済みのテンプレートが送信されます。

作成方法

デザイン JSON（content.email.design）を作成し、workflows-create-email-template で保存します。サーバーは、PostHog のビジュアルエディターと同じレンダラーを使ってデザインからメールをレンダリングするため、テンプレートは人が編集できるブロックとして開き、デザインの内容どおりに送信されます。スキーマ、すべてのメールに共通する標準ブロックと余白のルール、動作する例については、references/unlayer-design-json.md を参照してください。

ユーザーと話すときは、テンプレートのデザインと呼んでください。デザインドキュメントの形式は内部実装の詳細です。作成または更新後は、必ず返信にテンプレートの _posthogUrl 編集リンクを記載し、ユーザーが PostHog で直接開けるようにしてください。

作成前に references/design-guidelines.md を読んでください。デザインの方向性、タイポグラフィ、色、そしてメールを自動生成ではなく、きちんとデザインされたものに見せるパターンについて説明しています。ブロックエディターで表現できない断片がある場合は、デザイン内で html タイプのコンテンツブロックを使用してください。

Liquid によるパーソナライズ

メールのコンテンツでは Liquid テンプレートを使用します。Liquid タグはプレーンテキストとしてレンダラーを通過するため、ブロックのテキスト、件名、リンクなど、どこでも使用できます。

Hi {{ person.properties.first_name | default: 'there' }},

マーケティングメールには配信停止リンクを含める必要があります。組み込み変数を使ってレンダリングしてください。

<a href="{{ unsubscribe_url }}">Unsubscribe</a>

（1 クリックの配信停止フローには {{ unsubscribe_url_one_click }} も使用できます。） Customer.io 用に作成されたテンプレートでは、{% unsubscribe_url %} タグをそのまま使用できます。このタグは {{ unsubscribe_url }} と同じリンクをレンダリングします。

出力はデフォルトで HTML エスケープされるため、値にマークアップが含まれていてもテキストとしてレンダリングされます。

• | escape は追加しないでください。二重にエスケープされ、受信トレイには & と表示されます。
• サマリーリストなど、自分のバックエンドで作成した HTML には | raw を追加します。例：{{ variables.summary_html | raw }}。人が入力したテキストには raw を絶対に使用しないでください。
• currency を使って金額をフォーマットします。{{ variables.amount | currency: "USD" }} は $1,234.50 とレンダリングされます。数値以外の値は変更されずにレンダリングされます。

クリックトラッキングとオプトアウト

すべてのリンクは、クリックトラッキング用のリダイレクトを経由するよう自動的に書き換えられます。これはモバイルのユニバーサルリンクやアプリのディープリンクを壊します。これらのリンクは、href が同じドメイン上にある場合にのみ解決されるためです。リンクのトラッキングを無効にするには、アンカー（html ブロックを使用）に clicktracking="off" または data-ph-no-track を指定します。

<a href="https://app.example.com/deeplink" data-ph-no-track>Open in app</a>

マーカーは子要素ではなく、<a> タグ自体に指定する必要があります。オプトアウトされたリンクはクリック指標の対象になりません。

画像

まず purpose="email" を指定して media-images-list を呼び出し、重複してアップロードするのではなく、既存の画像（ロゴやヘッダーバナーなど）を再利用してください。

新しい画像を追加するには、デザインにバイト列を埋め込まず、署名付き URL を使うフローでアップロードします。

1. ファイル名と purpose="email" を指定して media-image-upload-start を呼び出します。id、upload_url、form_fields が返されます。
2. シェルから、ローカルファイルを upload_url に POST します。curl -X POST <upload_url> -F key=value... -F file=@/path/to/image.png（レスポンスの form_fields を指定し、file は最後にします）。画像のバイト列をツール呼び出しに Base64 エンコードして含めないでください。トークンが反転すると画像が破損します。
3. id を指定して media-image-upload-complete を呼び出すと、永続的な url が返されます。

その url を画像ブロックの values.src.url に指定してください（references/unlayer-design-json.md を参照）。ブロックには values.src.width／height も指定できます。メディアツールは寸法を返さないため、ローカルファイルにシェルからアクセスできる場合は、推測せずに自分で寸法を測定してください。

画像は 4MB 未満で、PNG、JPEG、GIF、WebP、AVIF、BMP のいずれかとしてデコードできる必要があります。

テンプレートの作成

workflows-create-email-template を次の内容で呼び出します。

{
  "name": "Welcome email",
  "description": "Sent to new signups on day 0",
  "type": "email",
  "content": {
    "templating": "liquid",
    "email": {
      "subject": "Welcome to {{ person.properties.company | default: 'our product' }}",
      "design": {
        "counters": { "u_row": 1 },
        "schemaVersion": 16,
        "body": { "rows": ["…"], "values": { "preheaderText": "Three short steps to get you set up" } }
      },
      "text": "Plain-text fallback of the same message"
    }
  }
}

• メールテンプレートでは subject が必須です。
• ほとんどの受信トレイで件名の後に表示されるプレビューテキストは、デザインの body.values.preheaderText に設定します。レンダリングされた HTML に含まれるため、どの送信経路でも受信トレイに表示されます。メールにプレビューテキストが 1 つだけ含まれるよう、content.email.preheader は未設定のままにします。
• 必ず design を作成し、html は省略します。サーバーがデザインから HTML をレンダリングします。デザインなしで手書きの HTML を送信すると、ビジュアルエディターではメールが 1 つの未加工ブロックとしてしか表示されません。
• 必ずメッセージを実際にプレーンテキスト化した text を指定します。リッチコンテンツをブロックするクライアントでは text のみが表示されるため、「placeholder」のような埋め草は実際の受信トレイに届きます。また、テキスト部分が HTML と一致しないと、到達率に悪影響があります。
• ツールの結果には、PostHog ライブラリ内の編集リンクが含まれます。
• 作成後（または更新後）は、workflows-show-email-template を呼び出します。インラインプレビューがレンダリングされ、ユーザーが結果を確認できます。

ペイロードの仕組み

デザインはツール呼び出しに直接渡します。一時ファイルの作成、事前検証のサブプロセス、ペイロードのプレビューを繰り返す必要はありません。Liquid タグ（{{ }}、{% %}）、アポストロフィ、シングルクォート、絵文字は JSON 文字列内の通常の文字です。標準の JSON エスケープのみが適用されます。これらを避けるためにコンテンツを書き換えてはいけません。マークアップ属性内で Liquid のシングルクォートをダブルクォートに変換すると、マークアップが壊れます。ツール呼び出しが不正な形式として拒否された場合は、JSON のエスケープを修正し、同じコンテンツを変更せずに再送信します。

既存の HTML メールの変換

別のプラットフォームのメールを移行するには、HTML を 1 つの html ブロックに貼り付けるのではなく、ネイティブブロックを使って再構築します。そうすることで、引き続き編集できるようになります。

• ソースの各パーツを、表示内容に対応するネイティブブロックにします。見出しは heading、段落ごとに text ブロック、各行動喚起に button、各画像に image を使います。各ブロックにはソースの色、フォントサイズ、パディングを維持します。
• すべての画像をメディアライブラリ経由で再ホストします（「画像」を参照）。ファイルの実際のサイズを src.width と src.height に指定し、コンテンツ幅に対する割合で表示幅を src.maxWidth に設定します。ソース HTML に指定された高さが、ファイルの実際のサイズと一致しないことはよくあります。
• ソースで {% if %} に囲まれたセクションは、表示条件を設定したブロックにします（references/unlayer-design-json.md を参照）。
• ソースプラットフォームの Liquid 変数を、この送信で使用する変数名に変更します。トランザクション API での送信では、呼び出し元が message_data で渡すすべての値を {{ variables.* }} として利用できます。
• ボタンには box-shadow がありません。暗い色合いの下枠（border.borderBottomWidth、borderBottomStyle、borderBottomColor）を 3px にすると、同じ立体的な見た目になります。
• social ブロックで描画できるのは、ブロック独自のアイコンセットのみです。カスタムアイコンを維持するには、再ホストした画像を使い、アイコンの行を html ブロックに配置します。

テンプレートの編集（読み取り・変更・書き込み）

更新時は content 全体が置き換えられ、マージはされません。また、最後に確認してから人が PostHog のビジュアルエディターでデザインを編集している可能性があります。

1. workflows-get-email-template — 必ず最新の情報を取得します。返された design が現在の信頼できる情報源です。
2. design を変更します（subject と text も併せて保持します）。
3. workflows-update-email-template — content 全体を送信します。サーバーは編集後のデザインから送信メールを再レンダリングします。
4. workflows-show-email-template — 更新したテンプレートをレンダリングして、ユーザーが変更を確認できるようにします。応答には最終的にレンダリングされた HTML が含まれるため、結果を説明する前に確認します。

既存のデザインに小さな変更を加える場合は、workflows-patch-email-template を優先します。Unlayer ブロックに対する ID 指定の操作を使用するため、デザイン全体ではなく変更内容だけを送信できます。

ワークフローのステップ内のメールを編集する

function_email ステップには、ライブラリテンプレートとは独立したメールのスナップショット（件名、テキスト、HTML、デザインを含む config.inputs.email.value）が保存されます。 workflows-patch-action-email で編集します。workflows-patch-email-template と同じデザイン操作に加え、件名、プリヘッダー、テキスト、宛先をマージする email_patch を使用できます。

1. workflows-get — ステップの現在のデザイン（およびブロック ID）は config.inputs.email.value.design にあります。
2. ワークフロー ID、ステップの action_id、操作および／または email_patch を指定して workflows-patch-action-email を呼び出します。操作によってコピーが変更される場合は、同じ呼び出しの email_patch で一致する text を設定します。
3. パッチ適用後のデザインからサーバー側で HTML が再レンダリングされるため、古い状態になることはありません。
4. アクティブなワークフローを編集すると、ドラフトが作成されます。workflows-test-run（use_draft=true）でテストし、workflows-publish で適用してください。

テンプレートを使用する

• workflows-list-email-templates で既存のテンプレートを一覧表示します（メタデータのみ。内容を取得するには個別に取得してください）。
• ユーザーがテンプレートの表示を求めた場合は、workflows-show-email-template を呼び出します。インラインプレビューが表示されます。
• ワークフローの function_email アクションでテンプレートを参照する（config.template_uuid に UUID を指定する）か、PostHog UI でテンプレートからブロードキャストを開始します。ステップには保存時点のテンプレート本文のスナップショットが保存されます。その後ライブラリ内のテンプレートを編集しても、すでに使用されているステップには反映されません。ステップのメールを変更するには、そのステップに workflows-patch-action-email を適用してください。
• workflows-update-email-template で deleted: true を設定すると、テンプレートは論理削除されます。