REST API リファレンス

すべてのパスは、https://shopify.workflow-transactional-email.app を基準としています。index 以外のすべてのエンドポイントには、Authorization: Bearer fak_... が必要です。詳細は 認証とAPIキー をご覧ください。

応答はJSON形式です。エラーの形式はすべて同じです：

{ "error": "Invalid or missing API key" }

指標と同一性

方法	パス	レベル	目的
GET	/api/v1	なし	APIインデックス。APIが稼働中であることを確認し、現在のリリース情報を報告します。
GET	/api/v1/me	読む	キーが機能するかどうかを確認し、そのアクセスレベルを確認してください

このインデックスにはキーが不要ですので、モニターを向けさせるのに適した安全なヘルスチェックとなります。

メールのレイアウト

方法	パス	レベル	目的
GET	/api/v1/email-templates	読む	メールのレイアウト一覧を表示します。q では、名前、件名、説明文で検索できます。category=transactional または category=marketing では、1つのメールタイプの一覧が表示されます。
投稿	/api/v1/email-templates	書く	レイアウトを作成する
GET	/api/v1/email-templates/:id	読む	1つのレイアウトとそのデザインや添付ファイル、フッターのテキスト、および対応言語の一覧
PUT / PATCH	/api/v1/email-templates/:id	書く	レイアウトを変更します。送信されるのは、変更したフィールドのみです。
DELETE	/api/v1/email-templates/:id	書く	レイアウトとその翻訳およびバージョンを削除する
GET	/api/v1/layout-schema	読む	レイアウトの作成方法：デザイン形式、各ブロックのデフォルト設定、使用可能なLiquid、制限事項、および例

このリストでは、page（デフォルト値：1）、limit（デフォルト値：25、最大値：100）、およびq（名前、件名、説明を検索）が指定可能です。API ではタイプによるフィルタリングは行われません。代わりに、各レイアウトに関する category をご参照ください。

レイアウトには、以下のフィールドがあります：

フィールド	注記
name, description	名前は必須で、最大200文字までです。説明は最大2000文字までです。
bodyType	visual （デフォルト）または text。一度作成されると変更できません
defaultLocale	レイアウト自体のコンテンツの言語です。設定されていない場合は、en となります。
category	transactional （デフォルト）または marketing。詳細は以下をご覧ください。
subject, previewText	飲み物の持ち込みは可能です。科目の履修が必須です。
bodyDesign	ビジュアルレイアウト：{ blocks, global?, header?, footer?, testVariables? }。変更の際は、完成したデザインを送ってください。HTML（body）はそこから生成されます。
body	テキストのレイアウト：HTMLのbody要素
attachments	テキストのレイアウト：アップロードされたファイルの場合は [{ filename, fileKey, sendAsLink? }] （以下のファイルをご参照ください）、またはメール送信時に https 経由で取得されるファイルの場合は [{ filename, url }] をご覧ください。
marketingTexts	マーケティング用レイアウトのフッターテキスト、あるいはnull。詳細は以下をご覧ください。

対象の「Liquid」、プレビューテキスト、本文、およびすべてのブロックテキストはパースされる必要があり、すべてのfileKeyはお客様のショップに属している必要があります。そうでない場合、そのフィールド名を指定した400エラーにより書き込みが拒否されます。ビジュアルデザインを作成する前に、GET /api/v1/layout-schema をお読みください。これはビルダー自体によって生成されるため、内容がずれることはありません。

このAPIを介して行われるすべての書き込みは、アプリでの保存とまったく同じように、レイアウトのバージョン履歴に記録されます。

トランザクション用およびマーケティング用のレイアウト

category レイアウトの目的について説明しています。トランザクション用レイアウトは、変更を加えることなくすべての受信者に送信されます。 マーケティング用レイアウトは、配信停止登録済みの受信者を除外し（このステップでは、「To」受信者全員が配信停止登録済みの場合は送信されず、履歴には「SKIPPED」と表示されます）、各「To」受信者ごとに個別の配信停止リンクを含む1通のメッセージとして送信され（1ステップあたり最大20通）、最後に配信停止に関する文言と貴社の詳細情報が記載されます。{{ unsubscribe_url }} および {{ unsubscribe_link }} には、ご自身でリンクを配置してください。トランザクション用レイアウトでは、これら両方が空欄となっています。これに関するマーチャント側の情報は、マーケティングメールと配信停止 に記載されています。

marketingTexts フッターの文言は、設定にある「サイト全体」のテキストの代わりに、マーケティングレイアウトで使用されるものですか：

{
  "marketingTexts": {
    "unsubscribeText": "You get this because you shop with us. {{ unsubscribe_link }}",
    "unsubscribeLinkLabel": "Unsubscribe",
    "companyDetails": "Example GmbH, Musterstrasse 1, 10115 Berlin"
  }
}

すべてのフィールドは任意です。設定されたフィールドは、そのフィールドの「設定」テキストを置き換えます。それ以外のフィールドはそのまま残ります。「null」（デフォルト）は、メールの言語に対応する「設定」テキストを意味します。制限：unsubscribeText および companyDetails は 2000 文字、unsubscribeLinkLabel は 100 文字です。 unsubscribeTextには、{{ unsubscribe_link }}または{{ unsubscribe_url }}が含まれている必要があります。そうでない場合、書き込みは拒否されます。このフィールドはどのレイアウトでも保存されますが、送信されるのはマーケティング用レイアウトの場合のみです。

レイアウトの削除は、いかなる場合でもブロックされることはありません。Shopify Flowのステップがまだそのレイアウトを参照している場合、レスポンスにはwarningというパラメータが含まれ、その数が示されます。それらのステップは、別のレイアウトを使用するまで失敗します。

翻訳

方法	パス	レベル	目的
GET	/api/v1/email-templates/:id/translations	読む	レイアウトに含まれるすべての言語とそのコンテンツ
GET	/api/v1/email-templates/:id/translations/:locale	読む	一つの言語
PUT	/api/v1/email-templates/:id/translations/:locale	書く	1つの言語を作成または上書きする
DELETE	/api/v1/email-templates/:id/translations/:locale	書く	1つの言語を削除します。その言語が削除されると、レイアウトがフォールバックします。
投稿	/api/v1/email-templates/:id/translations/:locale/promote	書く	その言語をレイアウトのメイン言語に設定してください

:locale de、fr、pt-br などの言語コードです。大文字小文字や区切り文字は問いません。1つのレイアウトにつき最大30言語まで指定できます。「Shopify Flow」ステップの**「Language**」フィールドでは、送信時に以下の順序で言語が選択されます：正確なロケール、次に基本言語、その次に地域別バリエーション、それ以外の場合はレイアウト自体となります。

PUTは、翻訳済みのコンテンツ全体（subject（必須）、previewText、およびbodyDesign（画像）またはbody（テキスト））を受け取ります。LiquidタグとURLは変更しないでください。翻訳に固有のフィールドは2つあります：

フィールド	テキストのレイアウト	意味
attachments	はい	リスト（レイアウトと同じ形式）＝その言語固有の添付ファイル、[]＝その言語には添付ファイルなし。null＝レイアウトの添付ファイルを送信します。省略＝現在の選択を維持します。新しい言語では、レイアウトのものが使用されます。ビジュアルレイアウトは、各言語のbodyDesign内にブロックとして添付ファイルを保持しており、このフィールドは使用しません。
marketingTexts	いずれか	この言語のフッターテキストは、レイアウトのフッターテキストの上に、フィールドごとに表示されます。「null」はレイアウトのフッターテキストを指します。「Omitted」は現在の選択内容を維持することを意味します。

翻訳結果には、同じ2つのフィールドが含まれています。「attachments」は「null」となり、レイアウトの値が返されます。また、「marketingTexts」は「null」となり、レイアウトの値が使用されます。

promote レイアウトと翻訳を入れ替えます。レイアウトは翻訳の内容とロケールを受け継ぎ、もともと持っていた内容は、以前属していた言語の翻訳となります。 添付ファイルやフッターのテキストも入れ替わりますので、各言語では以前と同じ内容を送信し続けます。レスポンスには、promoted、previousMainLanguage、およびレイアウトが返されます。これは1つのバージョンであるため、元に戻すことが可能です。

バージョン

方法	パス	レベル	目的
GET	/api/v1/email-templates/:id/versions	読む	保存されたバージョンを、新しい順に表示します。このアプリは最新の25件を保存します。
GET	/api/v1/email-templates/:id/versions/:version	読む	あるバージョンの完全なスナップショット：レイアウトおよびすべての翻訳
投稿	/api/v1/email-templates/:id/versions/:version/restore	書く	そのバージョンを元に戻してください。新しいバージョンとして録音されました。
GET	/api/v1/email-templates/:id/versions/github?page=	読む	接続されたGitHubリポジトリに保存されているすべてのバージョン（1ページにつき20件）
GET	/api/v1/email-templates/:id/versions/github/:sha	読む	あるコミット時点でのレイアウトは以下の通りでした
投稿	/api/v1/email-templates/:id/versions/github/:sha/restore	書く	GitHubのバージョンを元に戻し、保存のようにチェックします

「Developer」ページでリポジトリが接続されていない場合、GitHubのエンドポイントから409エラーが返されます。詳細は、レイアウトのバージョン履歴 および GitHubでレイアウトの履歴を無制限に保存する をご覧ください。

メールの送信者

方法	パス	レベル	目的
GET	/api/v1/smtp-configs	読む	SMTP送信元の一覧
GET	/api/v1/senders	読む	接続済みのメールボックスを一覧表示する（Microsoft 365、Google）

SMTPの送信者は、認証情報そのものではなく、「hasUsername」や「hasPassword」といった形式で報告します。ユーザー名はパスワードと同様に認証情報の一部であるため、両方の部分が非表示にされています。送信者は、その名前、ホスト、および送信元アドレスによって識別可能です。接続されたメールボックスは、「so***@example.com」のような一部がマスクされたアドレスを報告し、サインイントークンを報告することは決してありません。

読み取り専用です。アプリ内で送信者を登録・編集してください。

秘密

方法	パス	レベル	目的
GET	/api/v1/secrets	読む	秘密の名前と説明をリストアップしてください

hasValue を返しますが、値自体は決して返されません。シークレットを読み取るエンドポイントはありません。アプリ内でシークレットを作成および更新してください。

アップロードされたファイル

方法	パス	レベル	目的
GET	/api/v1/files	読む	アップロードされたロゴ、画像、および添付ファイルの一覧
DELETE	/api/v1/files	書く	本文中の「key」の記述を1か所削除してください

リストには、page、limit（最大100件）、およびqを指定して、ファイル名による検索を行うことができます。

?usage=true を追加すると、各ファイルには「inUse」に加え、それを参照しているレイアウトやプリセットの名前が記載された「usedBy」配列も表示されます。これにより、1回のリクエストで安全に削除できる項目をすべて特定できます。この機能はレイアウトやプリセットをスキャンするため、デフォルトでは有効になっておらず、明示的に有効にする必要があります。

ここではアップロード機能は提供されていません。アプリ内のメディアピッカーからファイルを追加してください。

HTTPリクエスト

方法	パス	レベル	目的
GET	/api/v1/http-requests	読む	HTTPリクエストの一覧を表示する
投稿	/api/v1/http-requests	書く	1つ作成する
GET	/api/v1/http-requests/:id	読む	1つお求めください
PUT / PATCH	/api/v1/http-requests/:id	書く	アップデートその1
DELETE	/api/v1/http-requests/:id	書く	1つ削除してください
投稿	/api/v1/http-requests/:id/test	実行する	実際のターゲットに対して実行してください

Listでは、メールレイアウトと同様に、page、limit、qの各パラメータを受け付けます。

対象の url は、http:// または https:// でなければなりません。それ以外の形式の場合は、保存時に拒否されます。

ヘッダーや本文に直接記述された認証情報は、すべてのレスポンスにおいてマスクされます。{{ secrets.KEY }} として参照される値は、参照自体に機密性がないため、記述されたままの形で返されます。

沿革と統計

メールの送信とHTTPリクエストの両方を対象としています。

方法	パス	レベル	目的
GET	/api/v1/history	読む	リストの実行
GET	/api/v1/history/:id	読む	リクエストおよびレスポンスデータを含む1つの実行結果を取得します
GET	/api/v1/stats	読む	合計数と成功率

Historyでは、page、limit（最大100）、actionType、status（PENDING、SUCCESS、FAILED、SKIPPED）、およびactionConfigIdを受け付け、単一のレイアウトまたはリクエストに絞り込むことができます。

SKIPPED これは、受信者全員が配信停止手続きを済ませていたマーケティングメールです。何も送信されておらず、上限も使用されておらず、成功率の算出対象にもなりません。

actionType EMAIL または HTTP_REQUEST のいずれかでなければなりません。認識されない値は拒否されるのではなく無視されるため、入力ミスがあってもエラーになるのではなく、すべての結果が返されます。

Statsでは、days（デフォルトは30、最大は365）を受け付けます。

ステータスコード

コード	意味
200	成功
201	作成日
400	リクエストの形式が不正であるか、検証に失敗しました。errorにはフィールド名を指定します。例：subject: required
401	APIキーが欠落している、形式が不正である、または無効化されている
403	キーは有効ですが、このエンドポイントに対してはレベルが低すぎます
404	見つかりませんでした、または別の店舗の商品です
405	このパスには不適切なメソッドです
409	レコードがまだ使用中であるため（ファイルの削除）、またはGitHubが接続されていないため（GitHubのバージョン）、処理が拒否されました。
429	レート制限あり - 詳細は以下をご覧ください
502	リクエストは実行されましたが、サードパーティのターゲットでエラーが発生しました

別の店舗に属するレコードが403ではなく404を返すため、APIではそのIDが他の場所に存在するかどうかの確認が一切行われません。

レート制限

2つの独立した予算で、いずれもキーごとです：

• すべてのエンドポイントにおいて、60秒あたり300件のリクエストです。
• さらに、1時間あたり60回の呼び出しを実行し、POST /api/v1/http-requests/:id/testをカバーします。

いずれかを超過すると、説明として「error」というエラーメッセージとともに429が返されます。実行予算は意図的に厳しく設定されています。支払いプロバイダーに対してリクエストを大量に送信し続ける暴走ループは、スクリプトの実行が遅くなるよりもはるかに深刻な障害となるからです。

予算はストアごとではなくキーごとに設定されるため、ある統合が別の統合の割り当てをすべて使い切ることはありません。