SendGrid コネクター
SendGrid アカウントを Tajo 経由で Brevo に接続して、メールインフラの移行、コンタクト同期、キャンペーンデータ転送、両プラットフォームにまたがる統一されたエンゲージメント分析を実現します。
概要
| 項目 | 値 |
|---|---|
| プラットフォーム | SendGrid (Twilio) |
| カテゴリー | マーケティング |
| セットアップ難易度 | 容易 |
| 公式統合 | あり |
| 同期データ | コンタクト、キャンペーン、トランザクショナルメール、イベント |
| API ベース URL | https://api.sendgrid.com/v3 |
機能
- コンタクト移行 - SendGrid マーケティングコンタクトをカスタムフィールドと共に Brevo へ移行
- トランザクショナルメール同期 - 統一レポート向けにトランザクショナルメールイベントを追跡
- キャンペーンデータ - Single Send と Automation のキャンペーンパフォーマンスデータを同期
- イベントウェブフック - メールイベント (delivered、opened、clicked、bounced) を Brevo へ転送
- 抑制リスト同期 - コンプライアンスのためバウンス、ブロック、配信停止リストを移行
- テンプレート移行 - Brevo で使用する Dynamic Transactional Templates をエクスポート
- 送信者認証 - 認証済み送信者 ID とドメイン認証を同期
- 統計同期 - 履歴のエンゲージメント統計を Brevo 属性にインポート
前提条件
開始する前に、以下をご用意ください。
- SendGrid アカウント (Free、Essentials、Pro、Premier)
- 必要な権限を持つ SendGrid API キー
- API アクセス付きの Brevo アカウント
- Tajo アカウント
認証
API キー認証
SendGrid はベアラートークン認証を使用します。
curl https://api.sendgrid.com/v3/marketing/contacts \ -H "Authorization: Bearer SG.YOUR_API_KEY" \ -H "Content-Type: application/json"API キーは SendGrid Settings > API Keys で特定の権限レベルを指定して作成できます。
- Full Access - 完全な API アクセス
- Restricted Access - きめ細かい権限制御
- Billing Access - 請求操作のみ
必要な権限
Marketing: Full Access - Contacts (read) - Single Sends (read) - Automations (read)Mail Send: Full Access - Mail Send (read)Stats: Read AccessSuppressions: Read AccessTracking: Read AccessAPI キーのセキュリティ
SendGrid API キーは作成時に一度だけ表示されます。安全に保管してください。紛失した場合は新しいキーを作成する必要があります。
設定
基本セットアップ
connectors: sendgrid: enabled: true api_key: "${SENDGRID_API_KEY}"
# Data sync options sync: contacts: true campaigns: true transactional: true suppressions: true statistics: true
# List mapping to Brevo list_mapping: "All Contacts": 60 "Newsletter": 61 "Transactional": 62フィールドマッピング
SendGrid のコンタクトフィールドを Brevo コンタクト属性にマッピングします。
既定のマッピング
| Parameter | Type | Description |
|---|---|---|
email required | string | コンタクトのメールアドレス (一意の識別子) |
first_name optional | string | FIRSTNAME 属性にマッピング |
last_name optional | string | LASTNAME 属性にマッピング |
phone_number optional | string | SMS 属性にマッピング |
city optional | string | コンタクトの市区町村 |
country optional | string | コンタクトの国 |
custom_fields optional | object | カスタムフィールドのキーバリューペア |
list_ids optional | array | SendGrid リストメンバーシップ |
カスタムフィールドマッピング
field_mapping: # Standard fields email: email first_name: FIRSTNAME last_name: LASTNAME phone_number: SMS
# Location fields city: CITY state_province_region: STATE country: COUNTRY postal_code: POSTAL_CODE
# Engagement metrics avg_open_rate: AVG_OPEN_RATE avg_click_rate: AVG_CLICK_RATE
# Custom fields custom_fields.company: COMPANY_NAME custom_fields.plan: PLAN_TYPEAPI エンドポイント
マーケティングコンタクト
| メソッド | エンドポイント | 説明 |
|---|---|---|
PUT | /v3/marketing/contacts | コンタクトを追加または更新 |
POST | /v3/marketing/contacts/search | コンタクト検索 |
GET | /v3/marketing/contacts/count | コンタクト数を取得 |
POST | /v3/marketing/contacts/exports | コンタクトをエクスポート |
DELETE | /v3/marketing/contacts | コンタクトを削除 |
GET | /v3/marketing/lists | すべてのコンタクトリスト一覧 |
トランザクショナルメール (Mail Send)
| メソッド | エンドポイント | 説明 |
|---|---|---|
POST | /v3/mail/send | メール送信 |
GET | /v3/templates | Dynamic Templates 一覧 |
GET | /v3/templates/{id} | テンプレート詳細を取得 |
キャンペーン (Single Sends)
| メソッド | エンドポイント | 説明 |
|---|---|---|
GET | /v3/marketing/singlesends | Single Sends 一覧 |
GET | /v3/marketing/singlesends/{id} | Single Send 詳細を取得 |
GET | /v3/marketing/automations | 自動化一覧 |
統計
| メソッド | エンドポイント | 説明 |
|---|---|---|
GET | /v3/stats | グローバルメール統計を取得 |
GET | /v3/categories/stats | カテゴリー統計を取得 |
GET | /v3/marketing/stats/singlesends | Single Send 統計を取得 |
抑制リスト
| メソッド | エンドポイント | 説明 |
|---|---|---|
GET | /v3/suppression/bounces | バウンスメール一覧 |
GET | /v3/suppression/blocks | ブロックメール一覧 |
GET | /v3/suppression/spam_reports | スパム報告一覧 |
GET | /v3/suppression/unsubscribes | グローバル配信停止一覧 |
イベント
メールイベント (Event Webhook 経由)
| イベント | トリガー | 用途 |
|---|---|---|
processed | SendGrid がメールを受理 | 送信確認 |
delivered | メールが受信者に配信 | 配信追跡 |
open | メール開封 | エンゲージメントスコアリング |
click | リンククリック | 関心追跡 |
bounce | メール不達 | リスト衛生 |
dropped | メールが抑制 | コンプライアンスレビュー |
deferred | 配信延期 | リトライ監視 |
spam_report | スパム報告 | レピュテーション管理 |
unsubscribe | リンク経由で配信停止 | 嗜好同期 |
コード例
コネクターの初期化
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
// Connect SendGridawait tajo.connectors.connect('sendgrid', { apiKey: process.env.SENDGRID_API_KEY});コンタクトの Brevo への移行
// Full contact migration from SendGrid to Brevoawait tajo.connectors.sync('sendgrid', { type: 'full', resources: ['contacts', 'suppressions'], options: { includeCustomFields: true, migrateListMemberships: true, migrateSuppressions: true }});
// Check migration statusconst status = await tajo.connectors.status('sendgrid');console.log(status);// {// connected: true,// lastSync: '2024-01-15T10:30:00Z',// contactsMigrated: 45000,// suppressionsSynced: 3200,// listsMapped: 8// }メールイベントの転送
// Handle SendGrid Event Webhookapp.post('/webhooks/sendgrid', async (req, res) => { const signature = req.get('X-Twilio-Email-Event-Webhook-Signature');
// Verify webhook signature (ECDSA) if (!verifySendGridSignature(req.body, signature)) { return res.status(401).send('Unauthorized'); }
// Process batch of events for (const event of req.body) { await tajo.connectors.handleWebhook('sendgrid', { type: event.event, email: event.email, timestamp: event.timestamp, payload: event }); }
res.status(200).send('OK');});レート制限
SendGrid API のレート制限:
| エンドポイント | 制限 | 詳細 |
|---|---|---|
Mail Send (/v3/mail/send) | プラン依存 | Free: 100/日、Essentials: プランによる |
| Marketing Contacts PUT | 3 リクエスト/秒 | 最大 30,000 コンタクトをバッチ処理 |
| Marketing Contacts Search | 50 リクエスト/秒 | API キーごと |
| 一般 API | 1,000 リクエスト/秒 | API キーごと |
| Event Webhook | バッチ配信 | POST あたり最大 1,000 イベント |
Mail Send の制限
Mail Send の制限は SendGrid プランに依存します。Free アカウントは 1 日 100 通までに制限されます。正確な送信上限はプランの詳細で確認してください。
トラブルシューティング
よくある問題
| 問題 | 原因 | 解決策 |
|---|---|---|
| 401 Unauthorized | 無効な API キー | SendGrid Settings で API キーを確認 |
| 403 Forbidden | API キー権限不足 | 必要なスコープを持つ新規キーを作成 |
| コンタクトエクスポート保留 | 大規模データセット処理中 | 完了までエクスポートステータスエンドポイントをポーリング |
| 抑制リスト同期が不完全 | ページネーション必要 | offset パラメータでページネーションを実装 |
| Event webhook が受信されない | URL 未検証 | SendGrid でウェブフック URL 検証を完了 |
デバッグモード
詳細ログを有効化します。
connectors: sendgrid: debug: true log_level: verbose log_webhooks: true接続テスト
tajo connectors test sendgrid# ✓ API connection successful# ✓ Contacts readable# ✓ Lists accessible# ✓ Statistics readable# ✓ Suppressions accessibleベストプラクティス
- 抑制リストを先に移行 - 送信前にバウンス、ブロック、配信停止を Brevo に反映
- コンタクト一括アップロードを使用 - 効率のためリクエストあたり最大 30,000 件を PUT
- Event Webhook を検証 - ECDSA 検証付き署名済みウェブフックを有効化
- カスタムフィールドをマッピング - コンタクト移行前に対応する Brevo 属性を作成
- エンゲージメントデータを同期 - Brevo でのセグメンテーション向けに履歴統計をインポート
- 非同期エクスポートを処理 - コンタクトエクスポートは非同期。完了をポーリングで確認
セキュリティ
- API キー認証 - きめ細かい権限レベルのベアラートークン
- Event Webhook 署名 - ウェブフックペイロードの ECDSA 署名検証
- TLS 暗号化 - すべての API 通信を HTTPS で暗号化
- IP アクセス管理 - Dashboard と API アクセスを IP で制限
- 二要素認証 - アカウントアクセスに 2FA 利用可能