SendGrid コネクター

SendGrid アカウントを Tajo 経由で Brevo に接続して、メールインフラの移行、コンタクト同期、キャンペーンデータ転送、両プラットフォームにまたがる統一されたエンゲージメント分析を実現します。

概要

項目
プラットフォームSendGrid (Twilio)
カテゴリーマーケティング
セットアップ難易度容易
公式統合あり
同期データコンタクト、キャンペーン、トランザクショナルメール、イベント
API ベース URLhttps://api.sendgrid.com/v3

機能

  • コンタクト移行 - SendGrid マーケティングコンタクトをカスタムフィールドと共に Brevo へ移行
  • トランザクショナルメール同期 - 統一レポート向けにトランザクショナルメールイベントを追跡
  • キャンペーンデータ - Single Send と Automation のキャンペーンパフォーマンスデータを同期
  • イベントウェブフック - メールイベント (delivered、opened、clicked、bounced) を Brevo へ転送
  • 抑制リスト同期 - コンプライアンスのためバウンス、ブロック、配信停止リストを移行
  • テンプレート移行 - Brevo で使用する Dynamic Transactional Templates をエクスポート
  • 送信者認証 - 認証済み送信者 ID とドメイン認証を同期
  • 統計同期 - 履歴のエンゲージメント統計を Brevo 属性にインポート

前提条件

開始する前に、以下をご用意ください。

  1. SendGrid アカウント (Free、Essentials、Pro、Premier)
  2. 必要な権限を持つ SendGrid API キー
  3. API アクセス付きの Brevo アカウント
  4. Tajo アカウント

認証

API キー認証

SendGrid はベアラートークン認証を使用します。

Terminal window
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 Access
Suppressions: Read Access
Tracking: Read Access

API キーのセキュリティ

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_TYPE

API エンドポイント

マーケティングコンタクト

メソッドエンドポイント説明
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/templatesDynamic Templates 一覧
GET/v3/templates/{id}テンプレート詳細を取得

キャンペーン (Single Sends)

メソッドエンドポイント説明
GET/v3/marketing/singlesendsSingle Sends 一覧
GET/v3/marketing/singlesends/{id}Single Send 詳細を取得
GET/v3/marketing/automations自動化一覧

統計

メソッドエンドポイント説明
GET/v3/statsグローバルメール統計を取得
GET/v3/categories/statsカテゴリー統計を取得
GET/v3/marketing/stats/singlesendsSingle Send 統計を取得

抑制リスト

メソッドエンドポイント説明
GET/v3/suppression/bouncesバウンスメール一覧
GET/v3/suppression/blocksブロックメール一覧
GET/v3/suppression/spam_reportsスパム報告一覧
GET/v3/suppression/unsubscribesグローバル配信停止一覧

イベント

メールイベント (Event Webhook 経由)

イベントトリガー用途
processedSendGrid がメールを受理送信確認
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 SendGrid
await tajo.connectors.connect('sendgrid', {
apiKey: process.env.SENDGRID_API_KEY
});

コンタクトの Brevo への移行

// Full contact migration from SendGrid to Brevo
await tajo.connectors.sync('sendgrid', {
type: 'full',
resources: ['contacts', 'suppressions'],
options: {
includeCustomFields: true,
migrateListMemberships: true,
migrateSuppressions: true
}
});
// Check migration status
const 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 Webhook
app.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 PUT3 リクエスト/秒最大 30,000 コンタクトをバッチ処理
Marketing Contacts Search50 リクエスト/秒API キーごと
一般 API1,000 リクエスト/秒API キーごと
Event Webhookバッチ配信POST あたり最大 1,000 イベント

Mail Send の制限

Mail Send の制限は SendGrid プランに依存します。Free アカウントは 1 日 100 通までに制限されます。正確な送信上限はプランの詳細で確認してください。

トラブルシューティング

よくある問題

問題原因解決策
401 Unauthorized無効な API キーSendGrid Settings で API キーを確認
403 ForbiddenAPI キー権限不足必要なスコープを持つ新規キーを作成
コンタクトエクスポート保留大規模データセット処理中完了までエクスポートステータスエンドポイントをポーリング
抑制リスト同期が不完全ページネーション必要offset パラメータでページネーションを実装
Event webhook が受信されないURL 未検証SendGrid でウェブフック URL 検証を完了

デバッグモード

詳細ログを有効化します。

connectors:
sendgrid:
debug: true
log_level: verbose
log_webhooks: true

接続テスト

Terminal window
tajo connectors test sendgrid
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Lists accessible
# ✓ Statistics readable
# ✓ Suppressions accessible

ベストプラクティス

  1. 抑制リストを先に移行 - 送信前にバウンス、ブロック、配信停止を Brevo に反映
  2. コンタクト一括アップロードを使用 - 効率のためリクエストあたり最大 30,000 件を PUT
  3. Event Webhook を検証 - ECDSA 検証付き署名済みウェブフックを有効化
  4. カスタムフィールドをマッピング - コンタクト移行前に対応する Brevo 属性を作成
  5. エンゲージメントデータを同期 - Brevo でのセグメンテーション向けに履歴統計をインポート
  6. 非同期エクスポートを処理 - コンタクトエクスポートは非同期。完了をポーリングで確認

セキュリティ

  • API キー認証 - きめ細かい権限レベルのベアラートークン
  • Event Webhook 署名 - ウェブフックペイロードの ECDSA 署名検証
  • TLS 暗号化 - すべての API 通信を HTTPS で暗号化
  • IP アクセス管理 - Dashboard と API アクセスを IP で制限
  • 二要素認証 - アカウントアクセスに 2FA 利用可能

関連リソース

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
AIアシスタント

こんにちは!ドキュメントについて何でもお聞きください。