sendgrid-automation

Rube MCP を使用した SendGrid の自動化

Composio の SendGrid ツールキットを通じて、マーケティングキャンペーン（Single Sends）、連絡先とリストの管理、送信者 ID の設定、メール分析など、SendGrid のメール配信ワークフローを自動化します。

前提条件

• Rube MCP が接続されていること（RUBE_SEARCH_TOOLS が利用可能）
• ツールキット sendgrid を指定した RUBE_MANAGE_CONNECTIONS による有効な SendGrid 接続
• 現在のツールスキーマを取得するため、必ず最初に RUBE_SEARCH_TOOLS を呼び出してください

セットアップ

Rube MCP を取得する：クライアントの設定で https://rube.app/mcp を MCP サーバーとして追加します。MCP サーバー／クライアントを認証し、SendGrid アカウントへのアクセスを許可してください。エンドポイントだけではアクセス権は付与されません。

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

主なワークフロー

1. マーケティングキャンペーン（Single Sends）の作成と送信

使用する場面：連絡先リストまたはセグメントにマーケティングメールキャンペーンを作成して送信する場合。

ツールの順序：

1. SENDGRID_RETRIEVE_ALL_LISTS - 配信対象として利用可能なマーケティングリストを一覧表示します［前提条件］
2. SENDGRID_CREATE_A_LIST - 必要に応じて新しいリストを作成します［任意］
3. SENDGRID_ADD_OR_UPDATE_A_CONTACT - 連絡先をリストに追加します［任意］
4. SENDGRID_GET_ALL_SENDER_IDENTITIES - 検証済みの送信者 ID を取得します［前提条件］
5. SENDGRID_CREATE_SINGLE_SEND - コンテンツ、送信者、受信者を設定してキャンペーンを作成します［必須］

SENDGRID_CREATE_SINGLE_SEND の主なパラメーター：

• name：キャンペーン名（必須）
• email__config__subject：メールの件名
• email__config__html__content：HTML 本文
• email__config__plain__content：プレーンテキスト版
• email__config__sender__id：検証済みの送信者 ID
• email__config__design__id：事前に作成したデザインを使用する場合は、html_content の代わりに指定します
• send__to__list__ids：配信先のリスト UUID の配列
• send__to__segment__ids：セグメント UUID の配列
• send__to__all：全連絡先に配信する場合は true
• email__config__suppression__group__id または email__config__custom__unsubscribe__url：サービス設定で必須となるいずれか一方。この設定だけで法令遵守が確立されるわけではありません

注意点：

• CREATE で send_at を設定しても、送信はスケジュールされません。UI の日付が事前入力されるだけです。別途 Schedule エンドポイントを使用してください
• send_at: "now" は Schedule エンドポイントでのみ有効で、CREATE では使用できません
• サービスが必須とする配信停止設定を指定し、それとは別に、該当する同意および配信停止の要件を確認してください
• 送信者は使用前に検証済みである必要があります。SENDGRID_GET_ALL_SENDER_IDENTITIES で確認してください
• ネストしたパラメーターには、二重アンダースコア表記を使用します（例：email__config__subject）

2. 連絡先とリストの管理

使用する場面：連絡先リストの作成、連絡先の追加・更新、連絡先の検索、リストからの連絡先の削除をユーザーが希望する場合。

ツールの手順：

1. SENDGRID_RETRIEVE_ALL_LISTS - マーケティングリストをすべて一覧表示します［必須］
2. SENDGRID_CREATE_A_LIST - 新しい連絡先リストを作成します［任意］
3. SENDGRID_GET_A_LIST_BY_ID - リストの詳細とサンプルの連絡先を取得します［任意］
4. SENDGRID_ADD_OR_UPDATE_A_CONTACT - リストとの関連付けとともに連絡先を追加または更新します［必須］
5. SENDGRID_GET_CONTACTS_BY_EMAILS - メールアドレスで連絡先を検索します［任意］
6. SENDGRID_GET_CONTACTS_BY_IDENTIFIERS - メールアドレス、電話番号、外部 ID で連絡先を検索します［任意］
7. SENDGRID_GET_LIST_CONTACT_COUNT - 操作後に連絡先数を確認します［任意］
8. SENDGRID_REMOVE_CONTACTS_FROM_A_LIST - 連絡先を削除せずにリストから除外します［任意］
9. SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS - リスト全体を削除します［任意］
10. SENDGRID_IMPORT_CONTACTS - CSV から一括インポートします［任意］

SENDGRID_ADD_OR_UPDATE_A_CONTACT の主なパラメーター：

• contacts：連絡先オブジェクトの配列（最大 30,000 件または 6MB）。各オブジェクトには、識別子として email、phone_number_id、external_id、anonymous_id のいずれかが少なくとも 1 つ必要です（必須）
• list_ids：連絡先を関連付けるリスト UUID 文字列の配列

注意点：

• SENDGRID_ADD_OR_UPDATE_A_CONTACT は非同期で動作し、job_id とともに 202 を返します。連絡先が表示されるまで 10～30 秒かかることがあります
• リスト ID は UUID（例：「ca7a3796-e8a8-4029-9ccb-df8937940562」）であり、整数ではありません
• リスト名は一意である必要があります。重複した名前は 400 エラーの原因になります
• SENDGRID_ADD_A_SINGLE_RECIPIENT_TO_A_LIST はレガシー API を使用します。list_ids を指定して SENDGRID_ADD_OR_UPDATE_A_CONTACT を使用してください
• SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS の操作は取り消せません。実行前にユーザーの明示的な確認を求めてください
• SendGrid によってメールアドレスは自動的に小文字に変換されます

3. 送信者 ID の管理

使用する場面：メール送信用の送信者 ID（From アドレス）の設定または確認をユーザーが希望する場合。

ツールの手順：

1. SENDGRID_GET_ALL_SENDER_IDENTITIES - 既存の送信者 ID をすべて一覧表示します［必須］
2. SENDGRID_CREATE_A_SENDER_IDENTITY - 新しい送信者 ID を作成します［任意］
3. SENDGRID_VIEW_A_SENDER_IDENTITY - 特定の送信者の詳細を表示します［任意］
4. SENDGRID_UPDATE_A_SENDER_IDENTITY - 送信者の詳細を更新します［任意］
5. SENDGRID_CREATE_VERIFIED_SENDER_REQUEST - 新しい送信者を作成して認証します［任意］
6. SENDGRID_AUTHENTICATE_A_DOMAIN - 自動認証のためにドメイン認証を設定します［任意］

SENDGRID_CREATE_A_SENDER_IDENTITY の主なパラメーター：

• from__email：From メールアドレス（必須）
• from__name：表示名（必須）
• reply__to__email：返信先アドレス（必須）
• nickname：内部識別子（必須）
• address、city、country：CAN-SPAM 準拠のための住所（必須）

注意点：

• 新しい送信者は使用前に認証が必要です。ドメインが認証されていない場合は、認証メールが送信されます
• アカウントごとに一意の送信者 ID を最大 100 件まで設定できます
• From アドレスには、厳格な DMARC ポリシーが適用されているドメイン（gmail.com、yahoo.com）の使用を避けてください
• SENDGRID_CREATE_VERIFIED_SENDER_REQUEST は認証メールを送信します。認証が完了するまで送信者は使用できません

4. メールの統計情報とアクティビティを確認する

使用する場面：ユーザーがメールの配信統計、バウンス率、開封・クリックの指標、またはメッセージのアクティビティを確認したい場合です。

ツールの実行順序：

1. SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS - アカウント全体の配信指標を取得します［必須］
2. SENDGRID_GET_ALL_CATEGORIES - フィルタリングに利用できるカテゴリを確認します［任意］
3. SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES - カテゴリ別の統計情報を取得します［任意］
4. SENDGRID_FILTER_ALL_MESSAGES - 宛先、ステータス、または日付でメールのアクティビティフィードを検索します［任意］
5. SENDGRID_FILTER_MESSAGES_BY_MESSAGE_ID - 特定のメッセージの詳細なイベントを取得します［任意］
6. SENDGRID_REQUEST_CSV - 大規模なデータセットのアクティビティデータを CSV 形式でエクスポートします［任意］
7. SENDGRID_DOWNLOAD_CSV - エクスポートした CSV ファイルをダウンロードします［任意］

SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS の主なパラメーター：

• start_date：開始日 YYYY-MM-DD（必須）
• end_date：終了日 YYYY-MM-DD
• aggregated_by：「day」、「week」、または「month」
• limit / offset：ページネーション（デフォルトは 500）

SENDGRID_FILTER_ALL_MESSAGES の主なパラメーター：

• query：SQL に似たクエリー文字列。例：status="delivered"、to_email="[email protected]"、BETWEEN TIMESTAMP を使った日付範囲
• limit：1～1000（デフォルトは 10）

注意点：

• SENDGRID_FILTER_ALL_MESSAGES を使用するには、有料アドオン「30 Days Additional Email Activity History」が必要です。アドオンがない場合は 403 が返されます
• 全体統計はフラットな構造ではなく、details[].stats[0].metrics 内にネストされています
• カテゴリ別の統計情報を取得できるのは、過去 13 か月分のみです
• SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES では、1 回のリクエストで最大 10 カテゴリまで指定できます
• CSV のエクスポートは 12 時間に 1 回までです。リンクの有効期限は 3 日後です

5. 配信停止設定を管理する

使用する場面：ユーザーがメール配信のコンプライアンス対応のために、配信停止グループを確認または管理したい場合です。

ツールの実行順序：

1. SENDGRID_GET_SUPPRESSION_GROUPS - すべての配信停止グループを一覧表示します［必須］
2. SENDGRID_RETRIEVE_ALL_SUPPRESSION_GROUPS_FOR_AN_EMAIL_ADDRESS - 特定のメールアドレスの配信停止ステータスを確認します［任意］

注意点：

• 配信停止されたアドレスは、マーケティングリストに登録されていても配信できません
• 配信停止設定により、キャンペーンの配信数がリストの件数を下回る場合があります

よくあるパターン

ID の解決

操作を行う前に、必ず名前を ID に解決してください：

• リスト名 -> list_id：SENDGRID_RETRIEVE_ALL_LISTS を使い、名前で照合します
• 送信者名 -> sender_id：SENDGRID_GET_ALL_SENDER_IDENTITIES を使い、照合します
• 連絡先のメールアドレス -> contact_id：メールアドレス配列を指定して SENDGRID_GET_CONTACTS_BY_EMAILS を使います
• テンプレート名 -> template_id：SendGrid UI またはテンプレートエンドポイントを使います

ページネーション

• SENDGRID_RETRIEVE_ALL_LISTS：page_token と page_size を使ったトークンベース（最大 1000）
• SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS：limit（最大 500）と offset を使ったオフセットベース
• 既存のリストを見落とさないよう、リスト取得時は常にページネーションを使用してください

非同期操作

連絡先の操作（ADD_OR_UPDATE_A_CONTACT、IMPORT_CONTACTS）は非同期です：

• job_id とともに 202 が返されます
• GET_CONTACTS_BY_EMAILS で確認する前に、10～30 秒待ってください
• 実際のジョブ結果と、意図した連絡先の所属状況を確認してください。件数が増えただけでは、すべての変更が成功した証拠にはなりません

既知の注意点

ID の形式

• マーケティングリスト ID は UUID です（例：「ca7a3796-e8a8-4029-9ccb-df8937940562」）
• レガシーリスト ID は整数です。マーケティング API のエンドポイントと混在させないでください
• 送信者 ID は整数です
• テンプレート ID：ダイナミックテンプレートは「d-」で始まり、レガシーテンプレートは UUID です
• 連絡先 ID は UUID です

レート制限

• SendGrid が HTTP 429 を返す場合があります。Retry-After ヘッダーに従ってください
• CSV のエクスポートは 12 時間に 1 回までです
• 連絡先の一括アップサートの上限は、1 リクエストあたり 30,000 件または 6MB です

パラメーターの注意点

• ネストされたパラメーターには二重アンダースコアを使用します：email__config__subject、from__email
• CREATE_SINGLE_SEND の send_at は UI のデフォルト値を設定するだけで、スケジュール設定は行いません
• SENDGRID_ADD_A_SINGLE_RECIPIENT_TO_A_LIST はレガシー API を使用します。recipient_id は小文字のメールアドレスを Base64 エンコードした値です
• SENDGRID_RETRIEVE_ALL_LISTS と SENDGRID_GET_ALL_LISTS の両方が存在します。Marketing API では RETRIEVE_ALL_LISTS を優先してください
• 連絡先の追加は非同期（202）です。必ず遅延を置いてから確認してください

レガシー API と Marketing API

• 一部のツールはレガシー Contact Database API（/v3/contactdb/）を使用しており、新しいアカウントでは 403 が返される場合があります
• Marketing API のツールを優先してください：SENDGRID_ADD_OR_UPDATE_A_CONTACT、SENDGRID_RETRIEVE_ALL_LISTS、SENDGRID_CREATE_SINGLE_SEND

クイックリファレンス

タスク	ツールスラッグ	主なパラメーター
マーケティングリストを一覧表示	SENDGRID_RETRIEVE_ALL_LISTS	page_size、page_token
リストを作成	SENDGRID_CREATE_A_LIST	name
ID でリストを取得	SENDGRID_GET_A_LIST_BY_ID	id
リストの連絡先数を取得	SENDGRID_GET_LIST_CONTACT_COUNT	id
連絡先を追加／更新	SENDGRID_ADD_OR_UPDATE_A_CONTACT	contacts、list_ids
メールアドレスで連絡先を検索	SENDGRID_GET_CONTACTS_BY_EMAILS	emails
識別子で検索	SENDGRID_GET_CONTACTS_BY_IDENTIFIERS	identifier_type、identifiers
リストから削除	SENDGRID_REMOVE_CONTACTS_FROM_A_LIST	id、contact_ids
リストを削除	SENDGRID_REMOVE_LIST_AND_OPTIONAL_CONTACTS	id、delete_contacts
連絡先を CSV でインポート	SENDGRID_IMPORT_CONTACTS	フィールドマッピング
Single Send を作成	SENDGRID_CREATE_SINGLE_SEND	name、email__config__*、send__to__list__ids
送信者 ID を一覧表示	SENDGRID_GET_ALL_SENDER_IDENTITIES	（なし）
送信者を作成	SENDGRID_CREATE_A_SENDER_IDENTITY	from__email、from__name、address
送信者を確認	SENDGRID_CREATE_VERIFIED_SENDER_REQUEST	from_email、nickname、address
ドメインを認証	SENDGRID_AUTHENTICATE_A_DOMAIN	domain
メールのグローバル統計	SENDGRID_RETRIEVE_GLOBAL_EMAIL_STATISTICS	start_date、aggregated_by
カテゴリー別統計	SENDGRID_RETRIEVE_EMAIL_STATISTICS_FOR_CATEGORIES	start_date、categories
メールアクティビティをフィルター	SENDGRID_FILTER_ALL_MESSAGES	query、limit
メッセージの詳細	SENDGRID_FILTER_MESSAGES_BY_MESSAGE_ID	msg_id
CSV をエクスポート	SENDGRID_REQUEST_CSV	query
CSV をダウンロード	SENDGRID_DOWNLOAD_CSV	download_uuid
カテゴリーを一覧表示	SENDGRID_GET_ALL_CATEGORIES	（なし）
抑制グループ	SENDGRID_GET_SUPPRESSION_GROUPS	（なし）
テンプレートを取得	SENDGRID_RETRIEVE_A_SINGLE_TRANSACTIONAL_TEMPLATE	template_id
テンプレートを複製	SENDGRID_DUPLICATE_A_TRANSACTIONAL_TEMPLATE	template_id、name

使用するタイミング

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

例

ユーザーのリクエスト：

Composio の SendGrid ツールキットを通じて、マーケティングキャンペーン（Single Sends）、連絡先とリストの管理、送信者 ID の設定、メール分析など、SendGrid のメール配信ワークフローを自動化してください。

制限事項

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

これは、過去のコネクターのスキーマと制限事項のスナップショットです。最新のディスカバリー情報とプロバイダーのドキュメントを優先してください。Single Send の作成は下書きであり、配信された証拠ではありません。明示的に許可された送信について、最終的な内容、送信者、対象者、送信時刻が確定している場合にのみ、実際のスケジュール／送信エンドポイントを特定してください。send_to_all を既定で使用しないでください。連絡先をインポートしても、同意が確認されたことにはならず、配信停止済みの受信者への再登録が許可されるわけでもありません。確認メール、送信者の変更、DNS 認証には、それぞれ個別に許可された対象が必要です。非同期ジョブは一定時間で完了すると決めつけず、上限を設けたバックオフでポーリングしてください。結果が不明な送信を繰り返さないでください。開封／クリックイベントは、本人ではなくプライバシープロキシやボットによる場合があります。エクスポートに含める受信者データを最小限にし、一時的なダウンロード URL を機密情報として扱ってください。