Konektor SendGrid

Hubungkan akun SendGrid Anda ke Brevo melalui Tajo untuk migrasi infrastruktur email, sinkronisasi kontak, transfer data kampanye, dan analitik keterlibatan terpadu di kedua platform.

Ikhtisar

Fitur

• Migrasi kontak - Migrasikan kontak SendGrid Marketing ke Brevo beserta field kustomnya
• Sinkronisasi email transaksional - Lacak event email transaksional untuk pelaporan terpadu
• Data kampanye - Sinkronkan data performa kampanye Single Send dan Automation
• Webhook event - Teruskan event email (delivered, opened, clicked, bounced) ke Brevo
• Sinkronisasi suppression - Migrasikan daftar bounce, block, dan unsubscribe demi kepatuhan
• Migrasi template - Ekspor Dynamic Transactional Template untuk dipakai di Brevo
• Verifikasi pengirim - Sinkronkan identitas pengirim terverifikasi dan autentikasi domain
• Sinkronisasi statistik - Impor statistik keterlibatan historis ke atribut Brevo

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

1. Akun SendGrid (Free, Essentials, Pro, atau Premier)
2. API key SendGrid dengan izin yang dibutuhkan
3. Akun Brevo dengan akses API
4. Akun Tajo

Autentikasi

Autentikasi API key

SendGrid memakai autentikasi bearer token.

curl https://api.sendgrid.com/v3/marketing/contacts \
  -H "Authorization: Bearer SG.YOUR_API_KEY" \
  -H "Content-Type: application/json"

Buat API key di SendGrid Settings > API Keys dengan tingkat izin tertentu:

• Full Access - Akses API sepenuhnya
• Restricted Access - Kontrol izin secara granular
• Billing Access - Operasi penagihan saja

Izin yang dibutuhkan

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

Konfigurasi

Setup dasar

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

Pemetaan field

Petakan field kontak SendGrid ke atribut kontak Brevo:

Pemetaan field kustom

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

Endpoint API

Marketing Contacts

Email transaksional (Mail Send)

Kampanye (Single Send)

Statistik

Suppression

Event

Event email (melalui Event Webhook)

Contoh kode

Inisialisasi konektor

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
});

Migrasi kontak ke 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
// }

Meneruskan event email

// 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');
});

Batas rate

Batas rate API SendGrid:

Pemecahan masalah

Masalah umum

Mode debug

Aktifkan logging verbose:

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

Menguji koneksi

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

Praktik terbaik

1. Migrasikan suppression lebih dulu - Pastikan bounce, block, dan unsubscribe sudah ada di Brevo sebelum mengirim
2. Gunakan unggahan kontak batch - Kirim PUT hingga 30.000 kontak per permintaan agar efisien
3. Verifikasi Event Webhook - Aktifkan webhook bertanda tangan dengan verifikasi ECDSA
4. Petakan field kustom - Buat atribut Brevo yang setara sebelum migrasi kontak
5. Sinkronkan data keterlibatan - Impor statistik historis untuk segmentasi di Brevo
6. Tangani ekspor asinkron - Ekspor kontak bersifat asinkron, lakukan polling sampai selesai

Keamanan

• Autentikasi API key - Bearer token dengan tingkat izin granular
• Penandatanganan Event Webhook - Verifikasi tanda tangan ECDSA untuk payload webhook
• Enkripsi TLS - Seluruh komunikasi API dienkripsi melalui HTTPS
• IP Access Management - Batasi akses Dashboard dan API berdasarkan IP
• Autentikasi dua faktor - 2FA tersedia untuk akses akun

Sumber daya terkait

• Dokumentasi API SendGrid
• Panduan SendGrid Event Webhook
• Konektor Brevo
• Konektor Mailchimp
• Skill Sinkronisasi Pelanggan