postmark-automation

Rube MCP を介した Postmark の自動化

Rube MCP を介して Composio の Postmark ツールキットを利用し、Postmark のトランザクションメール操作を自動化します。

前提条件

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

セットアップ

Rube MCP の取得：クライアント設定で https://rube.app/mcp を MCP サーバーとして追加します。MCP エンドポイントの利用には、プロバイダー接続と、インストール済みの Rube サービスが返す認証フローが引き続き必要です。URL を追加するだけでは、アカウントへのアクセス権は付与されません。

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

主なワークフロー

1. テンプレートを使った一括メール送信

使用する場面：ユーザーが複数の受信者にテンプレートメールを 1 回の呼び出しで送信したい場合

ツールの手順：

1. POSTMARK_LIST_TEMPLATES - 利用可能なテンプレートとその ID を検索します［必須］
2. POSTMARK_VALIDATE_TEMPLATE - 送信前にモデルデータを使ってテンプレートを検証します［任意］
3. POSTMARK_SEND_BATCH_WITH_TEMPLATES - テンプレートを使って一括メールを送信します［必須］

主なパラメーター：

• TemplateId または TemplateAlias：使用するテンプレートの識別子
• Messages：From、To、TemplateModel を含むメッセージオブジェクトの配列
• TemplateModel：テンプレート変数に一致するキーと値のペア

注意点：

• 1 回の一括呼び出しで送信できるメッセージは最大 500 件です
• TemplateId と TemplateAlias のどちらか一方が必須です。両方を指定することはできません
• TemplateModel のキーはテンプレート変数名と完全に一致する必要があります（大文字と小文字を区別します）
• 送信者アドレスは、検証済みの Sender Signature であるか、検証済みドメインに属している必要があります

2. メールテンプレートの管理

使用する場面：ユーザーがメールテンプレートを作成、編集、または確認したい場合

ツールの手順：

1. POSTMARK_LIST_TEMPLATES - ID と名前を含むすべてのテンプレートを一覧表示します［必須］
2. POSTMARK_GET_TEMPLATE - HTML／テキスト本文を含むテンプレートの詳細を取得します［任意］
3. POSTMARK_EDIT_TEMPLATE - テンプレートの内容または設定を更新します［任意］
4. POSTMARK_VALIDATE_TEMPLATE - サンプルデータでテンプレートのレンダリングをテストします［任意］

主なパラメーター：

• TemplateId：GET／EDIT 操作用の数値形式のテンプレート ID
• Name：テンプレートの表示名
• Subject：メールの件名（テンプレート変数に対応）
• HtmlBody：テンプレートの HTML コンテンツ
• TextBody：プレーンテキストの代替コンテンツ
• TemplateType：'Standard' または 'Layout'

注意点：

• テンプレート ID は文字列ではなく数値の整数です
• テンプレートを編集すると内容全体が置き換わります。保持したいフィールドはすべて含めてください
• Layout テンプレートは Standard テンプレートをラップします。Layout を変更すると、リンクされているすべてのテンプレートに影響します
• 送信前に検証し、不足している変数を早期に検出してください

3. 配信統計のモニタリング

使用する場面：ユーザーがメールの配信状況、開封率／クリック率、または送信メールの概要を確認したい場合

ツールの手順：

1. POSTMARK_GET_DELIVERY_STATS - 種類別のバウンス数を取得します［必須］
2. POSTMARK_GET_OUTBOUND_OVERVIEW - 送信数／開封数／クリック数／バウンス数の概要を取得します［必須］
3. POSTMARK_GET_TRACKED_EMAIL_COUNTS - 時間経過に伴う追跡対象メールの件数を取得します［任意］

主なパラメーター：

• fromdate：統計を絞り込む開始日（YYYY-MM-DD）
• todate：統計を絞り込む終了日（YYYY-MM-DD）
• tag：メッセージタグで統計を絞り込みます
• messagestreamid：メッセージストリームで絞り込みます（例：'outbound'、'broadcast'）

注意点：

• 日付パラメーターは YYYY-MM-DD 形式で指定します。時刻は含めません
• 統計は集計値です。個々のメッセージの追跡には別途 API 呼び出しが必要です
• messagestreamid を指定しない場合、すべてのストリームが対象になります

4. バウンスと苦情を管理する

使用するタイミング: ユーザーがバウンスしたメールやスパム苦情を確認したい場合

ツールの順序:

1. POSTMARK_GET_BOUNCES - 詳細付きでバウンスしたメッセージを一覧表示します [必須]
2. POSTMARK_GET_SPAM_COMPLAINTS - スパム苦情の記録を一覧表示します [任意]
3. POSTMARK_GET_DELIVERY_STATS - バウンスの集計件数を取得します [任意]

主なパラメータ:

• count: ページごとに返すレコード数
• offset: 結果のページネーションオフセット
• type: バウンスタイプのフィルター (例: 'HardBounce'、'SoftBounce'、'SpamNotification')
• fromdate/todate: 日付範囲フィルター
• emailFilter: 受信者のメールアドレスによるフィルター

注意点:

• バウンスタイプには以下が含まれます: HardBounce、SoftBounce、SpamNotification、SpamComplaint、Transient など
• ハードバウンスは恒久的な配信失敗を示します。これらのアドレスは削除する必要があります
• スパム苦情は送信者の評判に影響します。定期的に監視してください
• ページネーションにはページトークンではなく count と offset を使用します

5. サーバー設定を構成する

使用するタイミング: ユーザーが Postmark サーバーの構成を表示または変更したい場合

ツールの順序:

1. POSTMARK_GET_SERVER - 現在のサーバー設定を取得します [必須]
2. POSTMARK_EDIT_SERVER - サーバー構成を更新します [任意]

主なパラメータ:

• Name: サーバーの表示名
• SmtpApiActivated: SMTP API アクセスを有効/無効にします
• BounceHookUrl: バウンス通知用の Webhook URL
• InboundHookUrl: 受信メール処理用の Webhook URL
• TrackOpens: 開封トラッキングを有効/無効にします
• TrackLinks: リンクトラッキングモード ('None'、'HtmlAndText'、'HtmlOnly'、'TextOnly')

注意点:

• サーバーの編集は、そのサーバーを通じて送信されるすべてのメッセージに影響します
• Webhook URL は公開アクセス可能な HTTPS エンドポイントである必要があります
• SmtpApiActivated を変更すると SMTP リレーアクセスに影響します
• トラッキング設定は今後のメッセージにのみ適用され、過去には遡及しません

一般的なパターン

テンプレート変数の解決

1. Call POSTMARK_GET_TEMPLATE with TemplateId
2. Inspect HtmlBody/TextBody for {{variable}} placeholders
3. Build TemplateModel dict with matching keys
4. Call POSTMARK_VALIDATE_TEMPLATE to verify rendering

ページネーション

• ページあたりの結果数には count を設定します (エンドポイントによって異なります)
• 以前に取得した結果をスキップするには offset を使用します
• 返される結果が count 未満になるまで、各ページで offset を count 分増やします
• 総レコード数がレスポンスのメタデータに含まれる場合があります

既知の注意点

認証:

• Postmark はアカウントレベルではなくサーバーレベルの API トークンを使用します
• 各サーバーには独自のトークンがあります。正しいサーバーコンテキストを確認してください
• 送信者アドレスは、検証済みの Sender Signature であるか、検証済みドメインからのものである必要があります

レート制限:

• バッチ送信は 1 回の呼び出しにつき 500 メッセージに制限されています
• API レート制限はエンドポイントによって異なります。429 レスポンスに対してはバックオフを実装してください

レスポンスの解析:

• レスポンスデータは data または data.data の下にネストされている場合があります
• フォールバックパターンを使用して防御的に解析してください
• テンプレート ID は常に数値の整数です

クイックリファレンス

タスク	ツールスラッグ	主なパラメータ
テンプレート化されたメールをバッチ送信	POSTMARK_SEND_BATCH_WITH_TEMPLATES	Messages、TemplateId/TemplateAlias
テンプレートを一覧表示	POSTMARK_LIST_TEMPLATES	Count、Offset、TemplateType
テンプレートの詳細を取得	POSTMARK_GET_TEMPLATE	TemplateId
テンプレートを編集	POSTMARK_EDIT_TEMPLATE	TemplateId、Name、Subject、HtmlBody
テンプレートを検証	POSTMARK_VALIDATE_TEMPLATE	TemplateId、TemplateModel
配信統計	POSTMARK_GET_DELIVERY_STATS	(なし、または日付フィルター)
送信概要	POSTMARK_GET_OUTBOUND_OVERVIEW	fromdate、todate、tag
バウンスを取得	POSTMARK_GET_BOUNCES	count、offset、type、emailFilter
スパム苦情を取得	POSTMARK_GET_SPAM_COMPLAINTS	count、offset、fromdate、todate
トラッキングされたメール数	POSTMARK_GET_TRACKED_EMAIL_COUNTS	fromdate、todate、tag
サーバー構成を取得	POSTMARK_GET_SERVER	(なし)
サーバー構成を編集	POSTMARK_EDIT_SERVER	Name、TrackOpens、TrackLinks

使用するタイミング

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

制限事項

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

送信前に、サーバー／メッセージストリーム、受信者、正確な内容を確認してください。バッチ送信では、すべての項目を確認してください。各メッセージの結果を確認してください。HTTP の成功は、すべての受信者が承認または受信されたことを意味するわけではありません。再試行時の識別情報を保持し、不明な結果を照合してください。テンプレート／サーバーの追跡情報を変更すると他の送信にも影響するため、対象範囲を明示的に指定してください。トークンや非公開の受信者データは伏せてください。