mailchimp-automation

Rube MCP を使った Mailchimp の自動化

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

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

前提条件

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

セットアップ

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

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：1 ページあたりのレコード数（デフォルト 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 が使用されます
• 必須のマージフィールド検証を回避するには、skip_merge_validation: true を使用してください
• 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 でコンテンツを設定する必要があります
• テストメールを送信するには、キャンペーンのコンテンツがすでに設定されている必要があります

Quick Reference

Task	Tool Slug	Key Params
List audiences	MAILCHIMP_GET_LISTS_INFO	count, offset
Get audience details	MAILCHIMP_GET_LIST_INFO	list_id
Create campaign	MAILCHIMP_ADD_CAMPAIGN	type, recipients__list__id, settings__subject__line
Set campaign content	MAILCHIMP_SET_CAMPAIGN_CONTENT	campaign_id, html
Send test email	MAILCHIMP_SEND_TEST_EMAIL	campaign_id, test_emails
Send campaign	MAILCHIMP_SEND_CAMPAIGN	campaign_id
Schedule campaign	MAILCHIMP_SCHEDULE_CAMPAIGN	campaign_id, schedule_time
Get campaign info	MAILCHIMP_GET_CAMPAIGN_INFO	campaign_id
Search campaigns	MAILCHIMP_SEARCH_CAMPAIGNS	query
List campaigns	MAILCHIMP_LIST_CAMPAIGNS	status, count, offset
Replicate campaign	MAILCHIMP_REPLICATE_CAMPAIGN	campaign_id
List subscribers	MAILCHIMP_LIST_MEMBERS_INFO	list_id, status, count, offset
Search members	MAILCHIMP_SEARCH_MEMBERS	query, list_id
Get member info	MAILCHIMP_GET_MEMBER_INFO	list_id, subscriber_hash
Add subscriber	MAILCHIMP_ADD_MEMBER_TO_LIST	list_id, email_address, status
Upsert subscriber	MAILCHIMP_ADD_OR_UPDATE_LIST_MEMBER	list_id, subscriber_hash, email_address, status_if_new
Batch members	MAILCHIMP_BATCH_ADD_OR_REMOVE_MEMBERS	list_id, segment_id
List segments	MAILCHIMP_LIST_SEGMENTS	list_id
Campaign report	MAILCHIMP_GET_CAMPAIGN_REPORT	campaign_id
All reports	MAILCHIMP_LIST_CAMPAIGN_REPORTS	count, offset
Link click details	MAILCHIMP_LIST_CAMPAIGN_DETAILS	campaign_id, count
Subscriber activity	MAILCHIMP_GET_SUBSCRIBER_EMAIL_ACTIVITY	campaign_id, subscriber_hash
Member recent activity	MAILCHIMP_VIEW_RECENT_ACTIVITY	list_id, subscriber_hash
Campaign content	MAILCHIMP_GET_CAMPAIGN_CONTENT	campaign_id

---

Powered by Composio