Trình Kết Nối SendGrid

Kết nối tài khoản SendGrid của bạn với Brevo qua Tajo để migration hạ tầng email, đồng bộ contacts, chuyển dữ liệu campaign và hợp nhất engagement analytics trên cả hai nền tảng.

Tổng Quan

Tính Năng

• Migration contacts - Migrate Marketing contacts SendGrid sang Brevo với custom fields
• Đồng bộ transactional email - Theo dõi transactional email events cho báo cáo hợp nhất
• Dữ liệu campaign - Đồng bộ hiệu suất Single Send và Automation campaigns
• Event webhooks - Forward email events (delivered, opened, clicked, bounced) sang Brevo
• Đồng bộ suppression - Migrate bounce, block và unsubscribe lists để tuân thủ
• Migration template - Xuất Dynamic Transactional Templates để dùng trong Brevo
• Xác minh sender - Đồng bộ verified sender identities và domain authentication
• Đồng bộ statistics - Import historical engagement statistics sang thuộc tính Brevo

Yêu Cầu

Trước khi bắt đầu, hãy đảm bảo bạn có:

1. Tài khoản SendGrid (Free, Essentials, Pro, hoặc Premier)
2. SendGrid API key với quyền cần thiết
3. Tài khoản Brevo với quyền truy cập API
4. Tài khoản Tajo

Xác Thực

Xác Thực API Key

SendGrid sử dụng bearer token authentication.

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

Tạo API keys trong SendGrid Settings > API Keys với các cấp độ quyền cụ thể:

• Full Access - Toàn quyền truy cập API
• Restricted Access - Kiểm soát quyền chi tiết
• Billing Access - Chỉ thao tác billing

Quyền Cần Thiết

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

Cấu Hình

Thiết Lập Cơ Bản

connectors:
  sendgrid:
    enabled: true
    api_key: "${SENDGRID_API_KEY}"

    # Tùy chọn đồng bộ dữ liệu
    sync:
      contacts: true
      campaigns: true
      transactional: true
      suppressions: true
      statistics: true

    # Ánh xạ List sang Brevo
    list_mapping:
      "All Contacts": 60
      "Newsletter": 61
      "Transactional": 62

Ánh Xạ Trường

Ánh xạ trường contact SendGrid sang thuộc tính liên hệ Brevo:

Ánh Xạ Custom Field

field_mapping:
  # Trường tiêu chuẩn
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone_number: SMS

  # Trường vị trí
  city: CITY
  state_province_region: STATE
  country: COUNTRY
  postal_code: POSTAL_CODE

  # Số liệu tương tác
  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 Endpoints

Marketing Contacts

Transactional Email (Mail Send)

Campaigns (Single Sends)

Statistics

Suppressions

Sự Kiện

Email Events (qua Event Webhook)

Ví Dụ Code

Khởi Tạo Trình Kết Nối

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Kết nối SendGrid
await tajo.connectors.connect('sendgrid', {
  apiKey: process.env.SENDGRID_API_KEY
});

Migrate Contacts Sang Brevo

// Migration contacts đầy đủ từ SendGrid sang Brevo
await tajo.connectors.sync('sendgrid', {
  type: 'full',
  resources: ['contacts', 'suppressions'],
  options: {
    includeCustomFields: true,
    migrateListMemberships: true,
    migrateSuppressions: true
  }
});

// Kiểm tra trạng thái migration
const status = await tajo.connectors.status('sendgrid');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsMigrated: 45000,
//   suppressionsSynced: 3200,
//   listsMapped: 8
// }

Forward Email Events

// Xử lý SendGrid Event Webhook
app.post('/webhooks/sendgrid', async (req, res) => {
  const signature = req.get('X-Twilio-Email-Event-Webhook-Signature');

  // Xác minh webhook signature (ECDSA)
  if (!verifySendGridSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  // Xử lý batch 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');
});

Giới Hạn Tốc Độ

Giới hạn tốc độ API SendGrid:

Khắc Phục Sự Cố

Sự Cố Phổ Biến

Chế Độ Debug

Bật verbose logging:

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

Kiểm Tra Kết Nối

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

Thực Hành Tốt Nhất

1. Migrate suppressions trước - Đảm bảo bounces, blocks và unsubscribes có trong Brevo trước khi gửi
2. Sử dụng batch contact uploads - PUT tới 30.000 contacts mỗi request để hiệu quả
3. Xác minh Event Webhook - Bật signed webhooks với ECDSA verification
4. Ánh xạ custom fields - Tạo thuộc tính Brevo tương ứng trước khi migration contacts
5. Đồng bộ engagement data - Import historical stats cho phân đoạn trong Brevo
6. Xử lý async exports - Contact exports là bất đồng bộ; poll cho đến khi hoàn tất

Bảo Mật

• Xác thực API Key - Bearer token với các cấp độ quyền chi tiết
• Event Webhook signing - Xác minh chữ ký ECDSA cho webhook payloads
• Mã hóa TLS - Tất cả giao tiếp API được mã hóa qua HTTPS
• IP Access Management - Hạn chế Dashboard và API access theo IP
• Xác thực hai yếu tố - 2FA có sẵn để truy cập tài khoản

Tài Nguyên Liên Quan

• Tài Liệu API SendGrid
• Hướng Dẫn Event Webhook SendGrid
• Trình Kết Nối Brevo
• Trình Kết Nối Mailchimp
• Customer Sync Skill