---
title: "Trình Kết Nối SendGrid"
description: "Hướng dẫn tích hợp SendGrid đầy đủ để đồng bộ contacts, transactional emails, marketing campaigns và engagement events với Brevo qua Tajo."
url: https://tajo.io/vi/docs/connectors/marketing/sendgrid/
markdown: https://tajo.io/vi/docs/connectors/marketing/sendgrid.md
lang: vi-VN
robots: noindex
---

Đăng ký quyền truy cập sớm

Nhập tên và địa chỉ email công việc của bạn. Chúng tôi sẽ gửi liên kết để xác nhận yêu cầu truy cập Tajo.

# Trình Kết Nối SendGrid

Trạng thái trình kết nối: Đang phát triển Đang xây dựng. Chưa được xác minh.

| Trường nguồn | Trường đích | Giá trị mẫu |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

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

| Thuộc Tính | Giá Trị |
| --- | --- |
| **Nền Tảng** | SendGrid (Twilio) |
| **Danh Mục** | Marketing |
| **Độ Phức Tạp Thiết Lập** | Dễ |
| **Tích Hợp Chính Thức** | Không |
| **Dữ Liệu Đồng Bộ** | Contacts, Campaigns, Transactional Email, Sự Kiện |
| **URL API Cơ Sở** | `https://api.sendgrid.com/v3` |

## 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.

```bash
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
```

Bảo Mật API Key

SendGrid API keys chỉ hiển thị một lần khi tạo. Lưu trữ chúng an toàn. Nếu mất, bạn phải tạo key mới.

## Cấu Hình

### Thiết Lập Cơ Bản

```yaml
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ạ Mặc Định

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | Địa chỉ email liên hệ (định danh duy nhất) |
| `first_name` optional | string | Ánh xạ sang thuộc tính FIRSTNAME |
| `last_name` optional | string | Ánh xạ sang thuộc tính LASTNAME |
| `phone_number` optional | string | Ánh xạ sang thuộc tính SMS |
| `city` optional | string | Thành phố của liên hệ |
| `country` optional | string | Quốc gia của liên hệ |
| `custom_fields` optional | object | Các cặp key-value custom field |
| `list_ids` optional | array | Tư cách thành viên list SendGrid |

#### Ánh Xạ Custom Field

```yaml
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

| Phương Thức | Endpoint | Mô Tả |
| --- | --- | --- |
| `PUT` | `/v3/marketing/contacts` | Thêm hoặc cập nhật contacts |
| `POST` | `/v3/marketing/contacts/search` | Tìm kiếm contacts |
| `GET` | `/v3/marketing/contacts/count` | Lấy số lượng contacts |
| `POST` | `/v3/marketing/contacts/exports` | Xuất contacts |
| `DELETE` | `/v3/marketing/contacts` | Xóa contacts |
| `GET` | `/v3/marketing/lists` | Liệt kê tất cả contact lists |

### Transactional Email (Mail Send)

| Phương Thức | Endpoint | Mô Tả |
| --- | --- | --- |
| `POST` | `/v3/mail/send` | Gửi email |
| `GET` | `/v3/templates` | Liệt kê Dynamic Templates |
| `GET` | `/v3/templates/{id}` | Lấy chi tiết template |

### Campaigns (Single Sends)

| Phương Thức | Endpoint | Mô Tả |
| --- | --- | --- |
| `GET` | `/v3/marketing/singlesends` | Liệt kê Single Sends |
| `GET` | `/v3/marketing/singlesends/{id}` | Lấy chi tiết Single Send |
| `GET` | `/v3/marketing/automations` | Liệt kê Automations |

### Statistics

| Phương Thức | Endpoint | Mô Tả |
| --- | --- | --- |
| `GET` | `/v3/stats` | Lấy thống kê email toàn cầu |
| `GET` | `/v3/categories/stats` | Lấy thống kê category |
| `GET` | `/v3/marketing/stats/singlesends` | Lấy thống kê Single Send |

### Suppressions

| Phương Thức | Endpoint | Mô Tả |
| --- | --- | --- |
| `GET` | `/v3/suppression/bounces` | Liệt kê emails đã bounce |
| `GET` | `/v3/suppression/blocks` | Liệt kê emails bị block |
| `GET` | `/v3/suppression/spam_reports` | Liệt kê spam reports |
| `GET` | `/v3/suppression/unsubscribes` | Liệt kê global unsubscribes |

## Sự Kiện

### Email Events (qua Event Webhook)

| Sự Kiện | Kích Hoạt | Trường Hợp Sử Dụng |
| --- | --- | --- |
| `processed` | Email được SendGrid chấp nhận | Xác nhận gửi |
| `delivered` | Email được giao đến người nhận | Theo dõi giao hàng |
| `open` | Email được mở | Tính điểm tương tác |
| `click` | Link được nhấp | Theo dõi sở thích |
| `bounce` | Email bị bounce | Vệ sinh danh sách |
| `dropped` | Email bị suppress | Xem xét tuân thủ |
| `deferred` | Giao hàng bị trì hoãn | Theo dõi retry |
| `spam_report` | Bị đánh dấu là spam | Quản lý reputation |
| `unsubscribe` | Hủy đăng ký qua link | Đồng bộ tùy chọn |

## Ví Dụ Code

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

```javascript
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

```javascript
// 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

```javascript
// 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:

| Endpoint | Giới Hạn | Chi Tiết |
| --- | --- | --- |
| Mail Send (`/v3/mail/send`) | Theo gói | Free: 100/ngày, Essentials: dựa trên gói |
| Marketing Contacts PUT | 3 yêu cầu/giây | Batch tới 30.000 contacts |
| Marketing Contacts Search | 50 yêu cầu/giây | Mỗi API key |
| General API | 1.000 yêu cầu/giây | Mỗi API key |
| Event Webhook | Giao hàng batch | Tới 1.000 events mỗi POST |

Giới Hạn Mail Send

Giới hạn Mail Send phụ thuộc vào gói SendGrid của bạn. Tài khoản Free giới hạn 100 emails/ngày. Kiểm tra chi tiết gói của bạn để biết giới hạn gửi chính xác.

## Khắc Phục Sự Cố

### Sự Cố Phổ Biến

| Sự Cố | Nguyên Nhân | Giải Pháp |
| --- | --- | --- |
| 401 Unauthorized | API key không hợp lệ | Xác minh API key trong SendGrid Settings |
| 403 Forbidden | Quyền API key không đủ | Tạo key mới với đúng scopes |
| Xuất contacts đang chờ | Xử lý dataset lớn | Poll export status endpoint cho đến khi hoàn tất |
| Đồng bộ suppression không đầy đủ | Cần phân trang | Triển khai phân trang với tham số offset |
| Event webhook không nhận | URL chưa xác minh | Hoàn thành xác minh webhook URL trong SendGrid |

### Chế Độ Debug

Bật verbose logging:

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

### Kiểm Tra Kết Nối

```bash
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](https://docs.sendgrid.com/api-reference)
- [Hướng Dẫn Event Webhook SendGrid](https://docs.sendgrid.com/for-developers/tracking-events/event)
- [Trình Kết Nối Brevo](https://tajo.io/vi/docs/connectors/marketing/brevo)
- [Trình Kết Nối Mailchimp](https://tajo.io/vi/docs/connectors/marketing/mailchimp)
- [Customer Sync Skill](https://tajo.io/vi/docs/skills/data-sync/customer-sync)