mailchimp-automation

Rube MCP による Mailchimp の自動化

Composio の Mailchimp ツールキットを通じて、キャンペーンの作成と送信、オーディエンス／リストの管理、購読者の操作、セグメント化、パフォーマンス分析など、Mailchimp のメールマーケティングのワークフローを自動化します。

前提条件

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

セットアップ

既存の承認済み Rube 接続を使用してください。エンドポイントを設定しただけでは、Mailchimp の認証は行われません。セットアップを求められた場合は、サポートされているホストのフローを使用してください。

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

記載されているツールとデフォルト値は過去の情報です。検出されたスキーマを使用してください。下書きやキャンペーンの作成は、テスト送信、実際の送信、またはスケジュール設定の許可を意味しません。対象のオーディエンス／セグメント、配信停止・抑制の状態、送信者、コンテンツ、承認済みの受信者を正確に確認してください。適用される同意の証拠がない限り、既存の連絡先を再購読させたり、インポートした連絡先を購読済みとして登録したりしないでください。個人のエンゲージメントデータは最小限にとどめ、送信結果が不明な場合は再試行する前に状況を照合してください。

主なワークフロー

1. メールキャンペーンの作成と送信

使用する状況：ユーザーがメールキャンペーンの作成、設定、テスト、送信を希望している場合。

ツールの実行順序：

1. MAILCHIMP_GET_LISTS_INFO - 利用可能なオーディエンスを一覧表示し、list_id を取得します［前提条件］
2. MAILCHIMP_ADD_CAMPAIGN - 種類、オーディエンス、件名、送信者名を指定して新しいキャンペーンを作成します［必須］
3. MAILCHIMP_SET_CAMPAIGN_CONTENT - キャンペーンの HTML コンテンツを設定します［必須］
4. MAILCHIMP_SEND_TEST_EMAIL - 実際に送信する前に、レビュー担当者へプレビューを送信します［任意］
5. MAILCHIMP_SEND_CAMPAIGN - このキャンペーン／オーディエンスに対して明示的に依頼された場合に限り、直ちに送信します［任意の承認済みアクション］
6. MAILCHIMP_SCHEDULE_CAMPAIGN - 直ちに送信する代わりに、将来の配信日時を設定します［任意］

MAILCHIMP_ADD_CAMPAIGN の主なパラメーター：

• type：「regular」、「plaintext」、「rss」、または「variate」（必須）
• recipients__list__id：受信者のオーディエンス／リスト ID
• settings__subject__line：メールの件名
• settings__from__name：送信者の表示名
• settings__reply__to：返信先メールアドレス（送信に必須）
• settings__title：キャンペーンの内部タイトル
• settings__preview__text：受信トレイに表示されるプレビューテキスト

MAILCHIMP_SET_CAMPAIGN_CONTENT の主なパラメーター：

• campaign_id：作成手順で取得したキャンペーン ID（必須）
• html：メールの未加工 HTML コンテンツ
• plain_text：プレーンテキスト版（省略した場合は自動生成）
• template__id：未加工 HTML の代わりに、作成済みのテンプレートを使用します

注意点：

• MAILCHIMP_SEND_CAMPAIGN は取り消しできません。必ず先にテストメールを送信し、ユーザーから明示的な承認を得てください
• 送信前に、キャンペーンのステータスが「save」（下書き）であり、有効なオーディエンス、件名、送信者名、認証済みメールアドレス、コンテンツが設定されている必要があります
• MAILCHIMP_SCHEDULE_CAMPAIGN には有効な未来の日時が必要です。過去のタイムスタンプを指定すると失敗します
• テンプレートと HTML コンテンツには、規制に準拠したフッター／配信停止用のマージタグを含める必要があります
• Mailchimp では、ネストされたパラメーターに二重アンダースコア表記を使用します（例：settings__subject__line）

2. オーディエンスと購読者を管理する

使用する状況：ユーザーがオーディエンスの表示、購読者の一覧表示、または購読者の詳細確認を希望する場合。

ツールの順序：

1. MAILCHIMP_GET_LISTS_INFO - すべてのオーディエンスをメンバー数とともに一覧表示します［必須］
2. MAILCHIMP_GET_LIST_INFO - 特定のオーディエンスの詳細を取得します［任意］
3. MAILCHIMP_LIST_MEMBERS_INFO - ステータスフィルターとページネーションを指定してメンバーを一覧表示します［必須］
4. MAILCHIMP_SEARCH_MEMBERS - リスト全体からメールアドレスまたは名前で検索します［任意］
5. MAILCHIMP_GET_MEMBER_INFO - 特定の購読者の詳細なプロフィールを取得します［任意］
6. MAILCHIMP_LIST_SEGMENTS - オーディエンス内のセグメントを一覧表示します［任意］

MAILCHIMP_LIST_MEMBERS_INFO の主なパラメーター：

• list_id：オーディエンス ID（必須）
• status：「subscribed」、「unsubscribed」、「cleaned」、「pending」、「transactional」、「archived」
• count：ページあたりのレコード数（デフォルトは 10、最大 1000）
• offset：ページネーションのオフセット（デフォルトは 0）
• sort_field：「timestamp_opt」、「timestamp_signup」、または「last_changed」
• fields：レスポンスサイズを制限するためのカンマ区切りのリスト

注意点：

• stats.avg_open_rate と stats.avg_click_rate は 0～1 の小数であり、0～100 のパーセンテージではありません
• アクティブな購読者を絞り込むには、必ず status="subscribed" を使用してください。省略するとすべてのステータスが返されます
• 収集したメンバー数が total_items と一致するまで、count と offset を使ってページネーションする必要があります
• 大きなリストのレスポンスは途中で切り捨てられることがあります。データは response.data.members にあります

3. 購読者を追加・更新する

使用する状況：ユーザーが新しい購読者の追加、既存の購読者の更新、またはリストのメンバーシップの一括管理を希望する場合。

ツールの順序：

1. MAILCHIMP_GET_LIST_INFO - 対象のオーディエンスが存在することを確認します［前提条件］
2. MAILCHIMP_SEARCH_MEMBERS - 連絡先がすでに存在するか確認します［任意］
3. MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER - 購読者をアップサートします（作成または更新）［必須］
4. MAILCHIMP_ADD_MEMBER_TO_LIST - 新しい購読者を追加します（作成のみ）［任意］
5. MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS - セグメントのメンバーシップを一括管理します［任意］

MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER の主なパラメーター：

• list_id：オーディエンス ID（必須）
• subscriber_hash：小文字のメールアドレスの MD5 ハッシュ（必須）
• email_address：購読者のメールアドレス（必須）
• status_if_new：新しい購読者のステータス。「subscribed」、「pending」など（必須）
• status：既存の購読者のステータス
• merge_fields：マージタグのキーを含むオブジェクト（例：{"FNAME": "John", "LNAME": "Doe"}）
• tags：タグ文字列の配列

MAILCHIMP_ADD_MEMBER_TO_LIST の主なパラメーター：

• list_id：オーディエンス ID（必須）
• email_address：購読者のメールアドレス（必須）
• status：「subscribed」、「pending」、「unsubscribed」、「cleaned」、「transactional」（必須）

注意点：

• subscriber_hash は小文字のメールアドレスの MD5 ハッシュである必要があります。大文字・小文字が正しくないと、404 エラーや重複が発生します
• 重複エラーを避けるには、MAILCHIMP_ADD_MEMBER_TO_LIST の代わりに MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER（アップサート）を使用してください
• status_if_new は新しい連絡先のステータスのみを決定します。既存の連絡先には status が使われます
• マージフィールドの検証は維持してください。必須フィールドを省略するのは、ドキュメントに記載されたスキーマ上の根拠がある場合に限り、既定のエラー回避策として行わないでください
• MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS が管理するのは静的セグメントのメンバーシップであり、リストのメンバーシップではありません

4. キャンペーンレポートと分析を確認する

使用するタイミング：ユーザーがキャンペーンの成果、開封率、クリック率、または購読者のエンゲージメントを確認したい場合です。

ツールの実行順序：

1. MAILCHIMP_LIST_CAMPAIGNS - 送信済みキャンペーンをレポートの概要とともに一覧表示します［必須］
2. MAILCHIMP_SEARCH_CAMPAIGNS - 名前、件名、またはコンテンツでキャンペーンを検索します［任意］
3. MAILCHIMP_GET_CAMPAIGN_REPORT - キャンペーンの詳細なパフォーマンスレポートを取得します［必須］
4. MAILCHIMP_LIST_CAMPAIGN_REPORTS - 複数のキャンペーンのレポートを一括取得します［任意］
5. MAILCHIMP_LIST_CAMPAIGN_DETAILS - リンク単位のクリック統計を取得します［任意］
6. MAILCHIMP_GET_CAMPAIGN_LINK_DETAILS - 特定のリンクのクリックデータを詳しく確認します［任意］
7. MAILCHIMP_LIST_CLICKED_LINK_SUBSCRIBERS - 特定のリンクをクリックしたユーザーを確認します［任意］
8. MAILCHIMP_GET_SUBSCRIBER_EMAIL_ACTIVITY - 購読者ごとのキャンペーンアクティビティを取得します［任意］
9. MAILCHIMP_GET_CAMPAIGN_CONTENT - キャンペーンの HTML コンテンツを取得します［任意］

MAILCHIMP_LIST_CAMPAIGNS の主なパラメーター：

• status：「save」、「paused」、「schedule」、「sending」、「sent」
• count / offset：ページネーション（デフォルトは 10、最大 1000）
• since_send_time / before_send_time：ISO 8601 の日付範囲フィルター
• sort_field：「create_time」または「send_time」
• fields：パフォーマンス向上のため、レスポンスのフィールドを制限します

MAILCHIMP_GET_CAMPAIGN_REPORT の主なパラメーター：

• campaign_id：キャンペーン ID（必須）
• 返される内容：opens、clicks、bounces、unsubscribes、timeseries、industry_stats

注意点：

• MAILCHIMP_LIST_CAMPAIGNS が返すのは概要レベルの report_summary のみです。詳細な指標には MAILCHIMP_GET_CAMPAIGN_REPORT を使用してください
• 下書きまたは未送信のキャンペーンには、意味のあるレポートデータがありません
• LIST_CAMPAIGNS で fields パラメーターを使用する場合は、send_time と report_summary のサブフィールドを明示的に指定してください
• ページネーションのデフォルト値は少なめ（10 件）です。total_items を網羅するまで count と offset を使って繰り返し取得してください
• send_time はタイムゾーン付きの ISO 8601 形式です。慎重に解析してください

よくあるパターン

ID の解決

操作の前に、必ず名前から ID を解決してください：

• オーディエンス名 -> list_id：MAILCHIMP_GET_LISTS_INFO を使用し、名前で照合します
• 購読者のメールアドレス -> subscriber_hash：コード内で小文字に変換したメールアドレスの MD5 を計算します
• キャンペーン名 -> campaign_id：MAILCHIMP_SEARCH_CAMPAIGNS でクエリを指定します
• セグメント名 -> segment_id：MAILCHIMP_LIST_SEGMENTS に list_id を指定します

ページネーション

Mailchimp はオフセットベースのページネーションを使用します：

• count（ページサイズ、最大 1000）と offset（スキップするレコード数）を使用します
• レスポンスの total_items と収集済みレコード数が一致するまで続けます
• デフォルトの count は 10 です。一括操作では必ず明示的に設定してください
• 検索エンドポイントは最大 10 ページです（1 ページ 30 件の場合、最大 300 件）

購読者ハッシュ

多くのエンドポイントでは subscriber_hash（小文字に変換したメールアドレスの MD5）が必要です：

import hashlib
subscriber_hash = hashlib.md5(email.lower().encode()).hexdigest()

既知の注意点

ID の形式

• list_id（オーディエンス ID）は短い英数字の文字列です（例：「abc123def4」）
• campaign_id は英数字の文字列です
• subscriber_hash は MD5 の 16 進文字列（32 文字）です
• セグメント ID は整数です

レート制限

• Mailchimp は API のレート制限を適用します。一括の購読者操作にはバッチ処理を使用してください
• GET_MEMBER_INFO と ADD_OR_UPDATE_LIST_MEMBER を大量に使用すると、スロットリングが発生することがあります
• セグメントの一括操作には MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS を使用してください

パラメーターの注意点

• ネストされたパラメーターには、ダブルアンダースコア表記を使用します：settings__subject__line、recipients__list__id
• avg_open_rate と avg_click_rate は 0～1 の小数であり、パーセンテージではありません
• status_if_new は、アップサート操作で新規連絡先にのみ適用されます
• subscriber_hash は小文字に変換したメールアドレスの MD5 である必要があります。大文字・小文字が異なると、不要なレコードが作成されます
• キャンペーンの作成には type が必須です。最も一般的な値は「regular」です
• MAILCHIMP_SEND_CAMPAIGN は成功時に HTTP 204 を返します（ボディなし）

コンテンツとコンプライアンス

• キャンペーンの HTML には、配信停止リンクと住所（マージタグ）を含める必要があります
• 送信前に MAILCHIMP_SET_CAMPAIGN_CONTENT でコンテンツを設定する必要があります
• テストメールを送信するには、キャンペーンのコンテンツがすでに設定されている必要があります

クイックリファレンス

タスク	ツールスラッグ	主なパラメータ
オーディエンスを一覧表示	MAILCHIMP_GET_LISTS_INFO	count、offset
オーディエンスの詳細を取得	MAILCHIMP_GET_LIST_INFO	list_id
キャンペーンを作成	MAILCHIMP_ADD_CAMPAIGN	type、recipients__list__id、settings__subject__line
キャンペーンコンテンツを設定	MAILCHIMP_SET_CAMPAIGN_CONTENT	campaign_id、html
テストメールを送信	MAILCHIMP_SEND_TEST_EMAIL	campaign_id、test_emails
キャンペーンを送信	MAILCHIMP_SEND_CAMPAIGN	campaign_id
キャンペーンをスケジュール	MAILCHIMP_SCHEDULE_CAMPAIGN	campaign_id、schedule_time
キャンペーン情報を取得	MAILCHIMP_GET_CAMPAIGN_INFO	campaign_id
キャンペーンを検索	MAILCHIMP_SEARCH_CAMPAIGNS	query
キャンペーンを一覧表示	MAILCHIMP_LIST_CAMPAIGNS	status、count、offset
キャンペーンを複製	MAILCHIMP_REPLICATE_CAMPAIGN	campaign_id
購読者を一覧表示	MAILCHIMP_LIST_MEMBERS_INFO	list_id、status、count、offset
メンバーを検索	MAILCHIMP_SEARCH_MEMBERS	query、list_id
メンバー情報を取得	MAILCHIMP_GET_MEMBER_INFO	list_id、subscriber_hash
購読者を追加	MAILCHIMP_ADD_MEMBER_TO_LIST	list_id、email_address、status
購読者をアップサート	MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER	list_id、subscriber_hash、email_address、status_if_new
メンバーを一括処理	MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS	list_id、segment_id
セグメントを一覧表示	MAILCHIMP_LIST_SEGMENTS	list_id
キャンペーンレポート	MAILCHIMP_GET_CAMPAIGN_REPORT	campaign_id
すべてのレポート	MAILCHIMP_LIST_CAMPAIGN_REPORTS	count、offset
リンククリックの詳細	MAILCHIMP_LIST_CAMPAIGN_DETAILS	campaign_id、count
購読者のアクティビティ	MAILCHIMP_GET_SUBSCRIBER_EMAIL_ACTIVITY	campaign_id、subscriber_hash
メンバーの最近のアクティビティ	MAILCHIMP_VIEW_RECENT_ACTIVITY	list_id、subscriber_hash
キャンペーンコンテンツ	MAILCHIMP_GET_CAMPAIGN_CONTENT	campaign_id

使用する場合

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

制限事項

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