klaviyo-automation

Rube MCP による Klaviyo の自動化

Rube MCP を通じて Composio の Klaviyo ツールキットを利用し、Klaviyo のメールおよび SMS マーケティング業務を自動化します。

ツールキットのドキュメント：composio.dev/toolkits/klaviyo

前提条件

• Rube MCP が接続されている必要があります（RUBE_SEARCH_TOOLS を利用可能）
• ツールキット klaviyo を使用する RUBE_MANAGE_CONNECTIONS による有効な Klaviyo 接続
• 最新のツールスキーマを取得するため、必ず最初に RUBE_SEARCH_TOOLS を呼び出してください

セットアップ

Rube MCP を取得する：クライアントの構成に https://rube.app/mcp を MCP サーバーとして追加します。API キーは不要です。エンドポイントを追加するだけで動作します。

1. RUBE_SEARCH_TOOLS が応答することを確認し、Rube MCP が利用可能であることを確かめます
2. ツールキット klaviyo を指定して RUBE_MANAGE_CONNECTIONS を呼び出します
3. 接続が ACTIVE でない場合は、返された認証リンクに従って Klaviyo の認証を完了します
4. ワークフローを実行する前に、接続ステータスが ACTIVE であることを確認します

主なワークフロー

1. キャンペーンの一覧表示と絞り込み

使用する場面：マーケティングキャンペーンを閲覧、検索、または絞り込みたい場合

ツールの順序：

1. KLAVIYO_GET_CAMPAIGNS - チャネルとステータスのフィルターを指定してキャンペーンを一覧表示します［必須］

主なパラメーター：

• channel：キャンペーンのチャネル。「email」または「sms」（Klaviyo API で必須）
• filter：追加のフィルター文字列（例：equals(status,"draft")）
• sort：ソートフィールド。降順にする場合は先頭に - を付けます（例：'-created_at'、'name'）
• page_cursor：次のページを取得するためのページネーションカーソル
• include_archived：アーカイブ済みキャンペーンを含めます（デフォルト：false）

注意点：

• channel は必須です。省略すると、不完全または予期しない結果になることがあります
• 全件を取得するにはページネーションが必須です。1 回の呼び出しで返されるのは 1 ページのみです（デフォルトで約 10 件）
• すべてのキャンペーンを取得するには、page_cursor がなくなるまで続けてください
• filter によるステータスの絞り込み（例：equals(status,"draft")）では、複数のステータスが混在して返ることがあります。必ずクライアント側で data[].attributes.status を検証してください
• ステータス文字列は大文字と小文字が区別され、複合形式の場合があります（例：'Cancelled: No Recipients'）
• レスポンスはネストされています。ステータスは data[].attributes.status にあり、全体の構造は response.data.data です

2. キャンペーンの詳細を取得

使用する場面：特定のキャンペーンについて詳しい情報を知りたい場合

ツールの順序：

1. KLAVIYO_GET_CAMPAIGNS - キャンペーンを検索して ID を取得します［前提条件］
2. KLAVIYO_GET_CAMPAIGN - キャンペーンの詳細情報を取得します［必須］

主なパラメーター：

• campaign_id：キャンペーン ID 文字列（例：'01GDDKASAP8TKDDA2GRZDSVP4H'）
• include_messages：レスポンスにキャンペーンメッセージを含めます
• include_tags：レスポンスにタグを含めます

注意点：

• キャンペーン ID は英数字の文字列であり、数値ではありません
• include_messages と include_tags を指定すると、Klaviyo の include メカニズムを通じて関連データがレスポンスに追加されます
• キャンペーンの詳細には、オーディエンス、送信戦略、トラッキングオプション、スケジュール情報が含まれます

3. キャンペーンメッセージを確認

使用する場面：キャンペーンのメール／SMS の内容を確認したい場合

ツールの順序：

1. KLAVIYO_GET_CAMPAIGN - キャンペーンとそのメッセージ ID を取得します［前提条件］
2. KLAVIYO_GET_CAMPAIGN_MESSAGE - メッセージの内容の詳細を取得します［必須］

主なパラメーター：

• id：メッセージ ID 文字列
• fields__campaign__message：メッセージ属性のスパースフィールドセット（例：'content.subject'、'content.from_email'、'content.body'）
• fields__campaign：キャンペーン属性のスパースフィールドセット
• fields__template：テンプレート属性のスパースフィールドセット
• include：含める関連リソース（'campaign'、'template'）

注意点：

• メッセージ ID はキャンペーン ID とは別です。キャンペーンのレスポンスから抽出してください
• スパースフィールドセットの構文では、ネストされたフィールドにドット表記を使用します：'content.subject'、'content.from_email'
• メールメッセージには、subject、preview_text、from_email、from_label、reply_to_email のコンテンツフィールドがあります
• SMS メッセージには、body のコンテンツフィールドがあります
• 'template' を含めると、メールの HTML／テキストコンテンツが返されます

4. キャンペーンタグを管理する

使用する場面：組織のキャンペーンに関連付けられたタグを確認したい場合

ツールの実行順序：

1. KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS - キャンペーンのタグ ID を取得します［必須］

主なパラメーター：

• id：キャンペーン ID の文字列

注意点：

• 返されるのはタグ ID のみで、タグ名や詳細は含まれません
• タグ ID は、詳細を取得するために Klaviyo のタグエンドポイントで使用できます
• レート制限：バースト時は 3/s、通常時は 60/m（ほかのエンドポイントより厳しい制限です）

5. キャンペーン送信ジョブを監視する

使用する場面：キャンペーン送信処理のステータスを確認したい場合

ツールの実行順序：

1. KLAVIYO_GET_CAMPAIGN_SEND_JOB - 送信ジョブのステータスを確認します［必須］

主なパラメーター：

• id：送信ジョブ ID

注意点：

• キャンペーンの送信を開始すると、送信ジョブ ID が返されます
• ジョブのステータスは、送信がキューに登録済み、進行中、完了、または失敗のいずれかを示します
• レート制限：バースト時は 10/s、通常時は 150/m

よくあるパターン

キャンペーン検出パターン

1. Call KLAVIYO_GET_CAMPAIGNS with channel='email'
2. Paginate through all results via page_cursor
3. Filter by status client-side for accuracy
4. Extract campaign IDs for detailed inspection

スパースフィールドセットパターン

Klaviyo は、レスポンスサイズを減らすためにスパースフィールドセットをサポートしています。

fields__campaign__message=['content.subject', 'content.from_email', 'send_times']
fields__campaign=['name', 'status', 'send_time']
fields__template=['name', 'html', 'text']

ページネーション

• Klaviyo はカーソルベースのページネーションを使用します
• ページネーションメタデータで page_cursor がレスポンスに含まれているか確認します
• 次のリクエストでは、カーソルを page_cursor として渡します
• デフォルトのページサイズはキャンペーン約 10 件です
• カーソルが返されなくなるまで続けます

フィルター構文

- equals(status,"draft") - Campaigns in draft status
- equals(name,"Newsletter") - Campaign named "Newsletter"
- greater-than(created_at,"2024-01-01T00:00:00Z") - Created after date

既知の注意点

API バージョン：

• Klaviyo API はバージョン付きのエンドポイントを使用します（例：v2024-07-15）
• レスポンススキーマは API バージョン間で変更される場合があります
• ツールのレスポンスは、Composio インテグレーションで設定されたバージョンに従います

レスポンスのネスト：

• データはネストされています：response.data.data[].attributes
• キャンペーンのステータスは data[].attributes.status にあります
• ネストの解析を誤ると、結果が空になったり、不正確になったりします
• 常に完全なパスをたどるようにしてください

レート制限：

• バースト時：10/s（タグエンドポイントは 3/s）
• 通常時：150/m（タグエンドポイントは 60/m）
• 必須スコープ：campaigns:read
• 429 レスポンス時はバックオフを実装してください

ステータス値：

• ステータス文字列では大文字と小文字が区別されます
• 複合ステータスもあります（例：'Cancelled: No Recipients'）
• サーバー側のフィルタリングでは異なるステータスが混在して返される場合があるため、必ずクライアント側で検証してください

クイックリファレンス

タスク	ツールスラッグ	主なパラメーター
キャンペーンを一覧表示する	KLAVIYO_GET_CAMPAIGNS	channel, filter, sort, page_cursor
キャンペーンの詳細を取得する	KLAVIYO_GET_CAMPAIGN	campaign_id, include_messages, include_tags
キャンペーンメッセージを取得する	KLAVIYO_GET_CAMPAIGN_MESSAGE	id, fields__campaign__message
キャンペーンタグを取得する	KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS	id
送信ジョブのステータスを取得する	KLAVIYO_GET_CAMPAIGN_SEND_JOB	id

---

Composio を利用