---
title: "SendGrid 커넥터"
description: "Tajo를 통해 SendGrid의 연락처, 트랜잭션 이메일, 마케팅 캠페인, 참여 이벤트를 Brevo와 동기화하는 완전한 통합 가이드입니다."
url: https://tajo.io/kr/docs/connectors/marketing/sendgrid/
markdown: https://tajo.io/kr/docs/connectors/marketing/sendgrid.md
lang: ko-KR
robots: noindex
---

Tajo 사전 이용 신청

이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다.

# SendGrid 커넥터

커넥터 상태: 개발 중 구축 중입니다. 아직 검증되지 않았습니다.

| 원본 필드 | 대상 필드 | 예시 값 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

SendGrid 계정을 Tajo를 통해 Brevo에 연결하여 이메일 인프라 마이그레이션, 연락처 동기화, 캠페인 데이터 전송, 두 플랫폼 간의 통합된 참여 분석을 구현하십시오.

## 개요

| 속성 | 값 |
| --- | --- |
| **플랫폼** | SendGrid (Twilio) |
| **카테고리** | Marketing |
| **설정 복잡도** | 쉬움 |
| **공식 통합** | 아니오 |
| **동기화 데이터** | 연락처, 캠페인, 트랜잭션 이메일, 이벤트 |
| **API Base URL** | `https://api.sendgrid.com/v3` |

## 기능

- **연락처 마이그레이션** - 맞춤 필드와 함께 SendGrid Marketing 연락처를 Brevo로 마이그레이션
- **트랜잭션 이메일 동기화** - 통합 보고를 위한 트랜잭션 이메일 이벤트 추적
- **캠페인 데이터** - Single Send 및 Automation 캠페인 성능 데이터 동기화
- **이벤트 웹훅** - 이메일 이벤트(배달, 오픈, 클릭, 반송)를 Brevo로 전달
- **억제 동기화** - 규정 준수를 위해 반송, 차단, 구독 취소 목록 마이그레이션
- **템플릿 마이그레이션** - Brevo에서 사용할 Dynamic Transactional Templates 내보내기
- **발신자 검증** - 검증된 발신자 아이덴티티 및 도메인 인증 동기화
- **통계 동기화** - Brevo 속성에 과거 참여 통계 가져오기

## 사전 요구 사항

시작하기 전에 다음이 준비되어 있는지 확인하십시오.

1. SendGrid 계정 (Free, Essentials, Pro 또는 Premier)
2. 필수 권한이 있는 SendGrid API 키
3. API 접근이 가능한 Brevo 계정
4. Tajo 계정

## 인증

### API 키 인증

SendGrid는 Bearer 토큰 인증을 사용합니다.

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

특정 권한 수준으로 SendGrid Settings > API Keys에서 API 키를 생성하십시오:

- **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 키는 생성 시 한 번만 표시됩니다. 안전하게 저장하십시오. 분실한 경우 새 키를 생성해야 합니다.

## 구성

### 기본 설정

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

    # 데이터 동기화 옵션
    sync:
      contacts: true
      campaigns: true
      transactional: true
      suppressions: true
      statistics: true

    # 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 목록 멤버십 |

#### 맞춤 필드 매핑

```yaml
field_mapping:
  # 표준 필드
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone_number: SMS

  # 위치 필드
  city: CITY
  state_province_region: STATE
  country: COUNTRY
  postal_code: POSTAL_CODE

  # 참여 지표
  avg_open_rate: AVG_OPEN_RATE
  avg_click_rate: AVG_CLICK_RATE

  # 맞춤 필드
  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/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` | Automation 목록 |

### 통계

| 메서드 | 엔드포인트 | 설명 |
| --- | --- | --- |
| `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` | 링크를 통해 구독 취소됨 | 선호도 동기화 |

## 코드 예제

### 커넥터 초기화

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

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

// SendGrid 연결
await tajo.connectors.connect('sendgrid', {
  apiKey: process.env.SENDGRID_API_KEY
});
```

### 연락처를 Brevo로 마이그레이션

```javascript
// SendGrid에서 Brevo로의 전체 연락처 마이그레이션
await tajo.connectors.sync('sendgrid', {
  type: 'full',
  resources: ['contacts', 'suppressions'],
  options: {
    includeCustomFields: true,
    migrateListMemberships: true,
    migrateSuppressions: true
  }
});

// 마이그레이션 상태 확인
const status = await tajo.connectors.status('sendgrid');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsMigrated: 45000,
//   suppressionsSynced: 3200,
//   listsMapped: 8
// }
```

### 이메일 이벤트 전달

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

  // 웹훅 서명 확인 (ECDSA)
  if (!verifySendGridSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  // 이벤트 배치 처리
  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 요금제에 따라 다릅니다. 무료 계정은 100 이메일/일로 제한됩니다. 정확한 발송 제한은 요금제 세부 정보를 확인하십시오.

## 문제 해결

### 일반적인 문제

| 문제 | 원인 | 해결 방법 |
| --- | --- | --- |
| 401 Unauthorized | 잘못된 API 키 | SendGrid Settings에서 API 키 확인 |
| 403 Forbidden | API 키 권한 부족 | 필수 범위로 새 키 생성 |
| 연락처 내보내기 대기 중 | 대용량 데이터 세트 처리 | 완료될 때까지 내보내기 상태 엔드포인트 폴링 |
| 억제 동기화 불완전 | 페이지네이션 필요 | offset 매개변수로 페이지네이션 구현 |
| 이벤트 웹훅이 수신되지 않음 | URL이 검증되지 않음 | SendGrid에서 웹훅 URL 검증 완료 |

### 디버그 모드

자세한 로깅 활성화:

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

### 연결 테스트

```bash
tajo connectors test sendgrid
# ✓ API 연결 성공
# ✓ 연락처 읽기 가능
# ✓ 목록 접근 가능
# ✓ 통계 읽기 가능
# ✓ 억제 접근 가능
```

## 모범 사례

1. **억제를 먼저 마이그레이션** - 발송 전에 Brevo에 반송, 차단, 구독 취소가 있는지 확인
2. **배치 연락처 업로드 사용** - 효율성을 위해 요청당 최대 30,000 연락처 PUT
3. **Event Webhook 확인** - ECDSA 검증으로 서명된 웹훅 활성화
4. **맞춤 필드 매핑** - 연락처 마이그레이션 전에 해당하는 Brevo 속성 생성
5. **참여 데이터 동기화** - Brevo에서 세그먼테이션을 위한 과거 통계 가져오기
6. **비동기 내보내기 처리** - 연락처 내보내기는 비동기; 완료를 위해 폴링

## 보안

- **API 키 인증** - 세분화된 권한 수준의 Bearer 토큰
- **Event Webhook 서명** - 웹훅 페이로드에 대한 ECDSA 서명 확인
- **TLS 암호화** - HTTPS를 통해 암호화된 모든 API 통신
- **IP 접근 관리** - IP별 대시보드 및 API 접근 제한
- **이중 인증** - 계정 접근을 위한 2FA 사용 가능

## 관련 리소스

- [SendGrid API 문서](https://docs.sendgrid.com/api-reference)
- [SendGrid Event Webhook 가이드](https://docs.sendgrid.com/for-developers/tracking-events/event)
- [Brevo 커넥터](https://tajo.io/kr/docs/connectors/marketing/brevo)
- [Mailchimp 커넥터](https://tajo.io/kr/docs/connectors/marketing/mailchimp)
- [고객 동기화 스킬](https://tajo.io/kr/docs/skills/data-sync/customer-sync)