klaviyo-automation

Rube MCP による Klaviyo 自動化

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

前提条件

• Rube MCP が接続されている必要があります（RUBE_SEARCH_TOOLS が利用可能）
• RUBE_MANAGE_CONNECTIONS による有効な Klaviyo 接続（ツールキット 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'）になることがあります
• レスポンスの構造はネストされています: response.data.data で、ステータスは data[].attributes.status にあります

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

使用する場面

このスキルは、概要で説明されているワークフローまたはアクションを実行する場合に適用できます。

制限事項

• このスキルは、タスクが上記で説明した範囲に明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が欠けている場合は、停止して確認を求めてください。