DEV Community

Cover image for SMS 마케팅 Brevo API 활용법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

SMS 마케팅 Brevo API 활용법

요약

Brevo API를 사용하면 마케팅 이메일, 트랜잭션 이메일, SMS 메시지를 프로그래밍으로 전송할 수 있습니다. API 키 인증을 사용하여 api.brevo.com으로 요청을 보내고, 웹훅을 통해 전송 및 참여 이벤트를 추적합니다. 테스트 시 Apidog를 활용해 페이로드 검증, 웹훅 핸들러 검증, 통합 시 오류 및 구독 취소 처리를 점검하세요.

지금 Apidog 사용해보기

소개

Brevo(구 Sendinblue)는 50만 개 이상의 기업이 매일 수백만 건의 이메일을 처리할 수 있도록 지원합니다. 마케팅 캠페인, 트랜잭션 이메일, SMS 마케팅, 자동화 워크플로우까지 모두 제공합니다.

이메일 API는 단순한 전송을 넘어서 실제 운영 환경에서 반송, 스팸 신고, 구독 취소, 전송 지연 등 여러 상황을 다뤄야 합니다. Brevo는 이 복잡성을 추상화하여 사용자 개발 부담을 줄입니다.

API 주요 사용 사례:

  • 마케팅 캠페인: 대량 이메일 발송
  • 트랜잭션 이메일: 비밀번호 재설정, 주문 확인, 알림 등
  • SMS 메시지: 인증 코드, 알림, 마케팅 문자

💡 앱에 이메일 통합 시 Apidog를 활용해 템플릿 테스트, 웹훅 페이로드 검증, 이메일 클라이언트 전반에서 통합 정상 동작 확인이 가능합니다. 실제 이메일 전송 없이 Brevo 응답을 모의(Mock)해 오류 처리까지 테스트할 수 있습니다.

인증 및 설정

API 키 받기

  1. Brevo 개발자 센터에 로그인
  2. SMTP & API → API 키로 이동
  3. 필요한 권한으로 새 키 생성
  4. 안전하게 저장

API 키는 api-key 헤더에 추가합니다:

curl -X GET "https://api.brevo.com/v3/account" \
  -H "accept: application/json" \
  -H "api-key: your-api-key-here"
Enter fullscreen mode Exit fullscreen mode

API 기본 URL 

https://api.brevo.com/v3/
Enter fullscreen mode Exit fullscreen mode

전송량 제한

Brevo는 요금제에 따라 요청을 제한합니다:

  • 무료: 분당 300 요청
  • 스타터: 분당 600 요청
  • 비즈니스: 분당 1200 요청

X-RateLimit-Remaining 헤더로 사용량 추적이 가능합니다.

트랜잭션 이메일 전송

트랜잭션 이메일은 비밀번호 재설정, 주문 확인, 환영 이메일 등 사용자 행동에 의해 트리거됩니다.

간단한 이메일 보내기 

curl -X POST "https://api.brevo.com/v3/smtp/email" \
  -H "accept: application/json" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "sender": {
      "name": "Your App",
      "email": "noreply@yourapp.com"
    },
    "to": [
      {
        "email": "user@example.com",
        "name": "John Doe"
      }
    ],
    "subject": "Welcome to Our Platform",
    "htmlContent": "<html><body><h1>Welcome!</h1><p>Thanks for signing up.</p></body></html>",
    "textContent": "Welcome! Thanks for signing up."
  }'
Enter fullscreen mode Exit fullscreen mode

응답 예시:

{
  "messageId": "<20260324123456.123456@relay.brevo.com>"
}
Enter fullscreen mode Exit fullscreen mode

템플릿 사용

시각 편집기에서 템플릿 생성 후 ID로 전송:

curl -X POST "https://api.brevo.com/v3/smtp/email" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "templateId": 15,
    "to": [
      {
        "email": "user@example.com",
        "name": "John Doe"
      }
    ],
    "params": {
      "name": "John",
      "order_number": "ORD-12345",
      "tracking_url": "https://tracking.example.com/ORD-12345"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

템플릿 내 변수 사용 예시:

<p>Hi {{params.name}},</p>
<p>Your order {{params.order_number}} has shipped.</p>
<p><a href="{{params.tracking_url}}">Track your package</a></p>
Enter fullscreen mode Exit fullscreen mode

첨부 파일 포함 전송 

const response = await fetch('https://api.brevo.com/v3/smtp/email', {
  method: 'POST',
  headers: {
    'api-key': process.env.BREVO_API_KEY,
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    sender: { name: 'Your App', email: 'noreply@yourapp.com' },
    to: [{ email: 'user@example.com' }],
    subject: 'Your Invoice',
    htmlContent: '<p>Please find your invoice attached.</p>',
    attachment: [
      {
        name: 'invoice.pdf',
        content: base64EncodedPdfContent
      }
    ]
  })
})
Enter fullscreen mode Exit fullscreen mode

마케팅 캠페인

마케팅 이메일은 목록 전체로 발송하며, 구독 취소, 예약, 분석 기능이 포함됩니다.

캠페인 생성 

curl -X POST "https://api.brevo.com/v3/emailCampaigns" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "name": "March Newsletter",
    "subject": "What'\''s New in March",
    "sender": {
      "name": "Your Brand",
      "email": "newsletter@yourbrand.com"
    },
    "type": "classic",
    "htmlContent": "<html><body>Newsletter content here...</body></html>",
    "recipients": {
      "listIds": [12, 15]
    },
    "scheduledAt": "2026-03-25T09:00:00+00:00"
  }'
Enter fullscreen mode Exit fullscreen mode

즉시 보내기 

curl -X POST "https://api.brevo.com/v3/emailCampaigns/{campaignId}/sendNow" \
  -H "api-key: your-api-key"
Enter fullscreen mode Exit fullscreen mode

캠페인 통계 가져오기 

curl -X GET "https://api.brevo.com/v3/emailCampaigns/{campaignId}" \
  -H "api-key: your-api-key"
Enter fullscreen mode Exit fullscreen mode

응답 예:

{
  "statistics": {
    "delivered": 4850,
    "opened": 1455,
    "clicked": 291,
    "unsubscribed": 12,
    "bounces": 150
  }
}
Enter fullscreen mode Exit fullscreen mode

연락처 관리

연락처는 이메일 전송의 대상입니다. 목록 구성과 속성(커스텀 필드) 관리도 지원합니다.

연락처 생성 

curl -X POST "https://api.brevo.com/v3/contacts" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "email": "new.user@example.com",
    "attributes": {
      "FIRSTNAME": "Jane",
      "LASTNAME": "Smith",
      "PLAN": "premium"
    },
    "listIds": [12, 15],
    "updateEnabled": true
  }'
Enter fullscreen mode Exit fullscreen mode

updateEnabled: true를 사용하면 기존 연락처도 업데이트됩니다.

연락처 세부 정보 가져오기 

curl -X GET "https://api.brevo.com/v3/contacts/user@example.com" \
  -H "api-key: your-api-key"
Enter fullscreen mode Exit fullscreen mode

목록에 추가 

curl -X POST "https://api.brevo.com/v3/contacts/lists/12/contacts/add" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "emails": ["user1@example.com", "user2@example.com"]
  }'
Enter fullscreen mode Exit fullscreen mode

목록에서 제거 

curl -X DELETE "https://api.brevo.com/v3/contacts/lists/12/contacts/remove" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "emails": ["user@example.com"]
  }'
Enter fullscreen mode Exit fullscreen mode

연락처 구독 취소 

curl -X PUT "https://api.brevo.com/v3/contacts/user@example.com" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "emailBlacklisted": true
  }'
Enter fullscreen mode Exit fullscreen mode

SMS 마케팅

Brevo SMS API로 글로벌 SMS 전송이 가능합니다.

SMS 보내기 

curl -X POST "https://api.brevo.com/v3/transactionalSMS/sms" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "sender": "YourApp",
    "recipient": "+15551234567",
    "content": "Your verification code is: 123456",
    "type": "transactional"
  }'
Enter fullscreen mode Exit fullscreen mode

마케팅 SMS 보내기 

curl -X POST "https://api.brevo.com/v3/transactionalSMS/sms" \
  -H "api-key: your-api-key" \
  -H "content-type: application/json" \
  -d '{
    "sender": "YourBrand",
    "recipient": "+15551234567",
    "content": "Flash sale! 50% off today only. Reply STOP to unsubscribe.",
    "type": "marketing"
  }'
Enter fullscreen mode Exit fullscreen mode

SMS 통계 조회 

curl -X GET "https://api.brevo.com/v3/transactionalSMS/statistics?startDate=2026-03-01&endDate=2026-03-31" \
  -H "api-key: your-api-key"
Enter fullscreen mode Exit fullscreen mode

추적을 위한 웹훅

웹훅은 이메일 이벤트(전송, 열림, 클릭, 반송, 구독 취소 등)를 실시간으로 알려줍니다.

웹훅 구성

Brevo 대시보드: 설정 → 웹훅 → 웹훅 추가

추적 이벤트:

  • delivered: 이메일 도달
  • opened: 열람됨
  • clicked: 링크 클릭
  • bounced: 반송(하드/소프트)
  • spam: 스팸 신고
  • unsubscribed: 구독 취소

웹훅 페이로드 처리 예제 

app.post('/webhooks/brevo', (req, res) => {
  const event = req.body

  switch (event.event) {
    case 'delivered':
      console.log(`Email ${event.messageId} delivered to ${event.email}`)
      break
    case 'opened':
      console.log(`Email opened by ${event.email} at ${event.date}`)
      break
    case 'bounced':
      console.log(`Bounce: ${event.email} - ${event.reason}`)
      markContactBounced(event.email)
      break
    case 'spam':
      console.log(`Spam complaint from ${event.email}`)
      removeFromAllLists(event.email)
      break
    case 'unsubscribed':
      console.log(`Unsubscribed: ${event.email}`)
      break
  }
  res.status(200).send('OK')
})
Enter fullscreen mode Exit fullscreen mode

Apidog로 테스트하기

이메일 API는 반송/실패 등 다양한 복잡한 시나리오가 있으므로, 템플릿·웹훅·반송 등 다양한 상황을 Apidog에서 쉽게 검증할 수 있습니다.

Apidog 테스트

1. 이메일 전송 모의(Mock)

실제 이메일 전송 없이 응답을 모의:

pm.test('Email API accepts valid payload', () => {
  const response = pm.response.json()
  pm.expect(response).to.have.property('messageId')
  pm.expect(response.messageId).to.match(/<.*@relay\.brevo\.com>/)
})
Enter fullscreen mode Exit fullscreen mode

Apidog Mock

2. 웹훅 처리 테스트

Apidog에서 모의 페이로드 생성 후 엔드포인트 검증:

{
  "event": "bounced",
  "email": "invalid@example.com",
  "messageId": "<12345@relay.brevo.com>",
  "reason": "hard_bounce",
  "date": "2026-03-24T12:00:00Z",
  "subject": "Welcome to Our Platform"
}
Enter fullscreen mode Exit fullscreen mode

3. 템플릿 유효성 검사

템플릿 변수 검증:

pm.test('Template variables are valid', () => {
  const payload = pm.request.body.toJSON()
  pm.expect(payload.params).to.have.property('name')
  pm.expect(payload.params).to.have.property('order_number')
})
Enter fullscreen mode Exit fullscreen mode

4. 환경 분리 

# Development
BREVO_API_KEY: xkeysib-dev-xxx
BREVO_SENDER: dev@yourapp.com

# Production
BREVO_API_KEY: xkeysib-prod-xxx
BREVO_SENDER: noreply@yourapp.com
Enter fullscreen mode Exit fullscreen mode

Apidog로 Brevo 이메일 API를 무료로 테스트할 수 있습니다.

일반적인 오류 및 해결 방법

400 Bad Request - 필수 필드 누락

원인: 필수 필드 누락

해결: 오류 메시지 확인

{
  "code": "invalid_parameter",
  "message": "sender.email is required"
}
Enter fullscreen mode Exit fullscreen mode

401 Unauthorized

원인: 잘못된 또는 누락된 API 키

해결: api-key 헤더 및 키 상태 확인

402 Payment Required

원인: 한도 초과, 크레딧 부족

해결:

  • 이메일: 요금제 한도 확인
  • SMS: 크레딧 구매

429 Too Many Requests

원인: 전송량 제한 초과

해결: 지수 백오프(exponential backoff) 적용

async function sendWithRetry(email, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await sendEmail(email)
    if (response.status === 429) {
      await sleep(Math.pow(2, i) * 1000)
    } else {
      return response
    }
  }
  throw new Error('Rate limit exceeded')
}
Enter fullscreen mode Exit fullscreen mode

404 연락처를 찾을 수 없음

원인: 없는 연락처 업데이트 시도

해결: updateEnabled: true 사용

{
  "email": "new@example.com",
  "updateEnabled": true
}
Enter fullscreen mode Exit fullscreen mode

대안 및 비교

기능 Brevo SendGrid Mailchimp Postmark
가격 정책 일일 300 이메일 무료 일일 100 이메일 무료 월 500 이메일 무료 월 100 이메일 무료
마케팅 이메일 예 예 예 아니요
트랜잭션 이메일 예 예 제한적 예 (전문)
SMS 예 아니요 아니요 아니요
자동화 예 예 예 제한적
템플릿 편집기 시각 + 코드 코드 시각 코드

Brevo는 이메일과 SMS를 결합한 경쟁력 있는 가격 정책이 장점입니다.

실제 사용 사례

전자상거래 주문 플로우:

온라인 스토어는 Brevo로 주문 확인(트랜잭션), 배송 알림(트랜잭션), 장바구니 포기 복구(마케팅 자동화), 주간 프로모션(마케팅 캠페인)을 통합 관리합니다.

SaaS 온보딩:

프로젝트 관리 SaaS는 트랜잭션 API로 환영 이메일, 비밀번호 재설정, 팀 초대 발송. 마케팅 이메일로 신규 기능 공지.

SMS 인증:

핀테크 앱은 SMS API로 2단계 인증 코드 발송. 트랜잭션 SMS 엔드포인트로 빠르게 코드 전송, 웹훅으로 전송 실패 추적 및 재시도 처리.

결론

정리:

  • Brevo API로 마케팅, 트랜잭션 이메일, SMS 모두 처리
  • api-key 헤더로 인증
  • 템플릿 활용으로 일관된 이메일 유지
  • 연락처/목록 관리로 타겟 캠페인 가능
  • 웹훅으로 전송/열람/클릭/반송 추적
  • Apidog로 실제 발송 전 통합 테스트

다음 단계:

  1. Brevo 계정 생성 및 API 키 발급
  2. 첫 트랜잭션 이메일 전송
  3. 시각 편집기에서 템플릿 생성
  4. 반송/구독취소용 웹훅 핸들러 구축
  5. 개발 단계에서 Apidog로 테스트

Apidog로 Brevo 이메일 API 무료 테스트

자주 묻는 질문

Brevo와 Sendinblue의 차이는?

동일 제품의 리브랜딩(2023년 Sendinblue → Brevo). API 엔드포인트는 계속 api.brevo.com 사용.

무료로 이메일 몇 통 보낼 수 있나요?

무료 요금제: 하루 300건(월 9,000건). 더 많은 발송은 유료 플랜 필요.

콜드 이메일도 가능합니까?

기술적으로 가능하지만, 반송/스팸률이 높으면 계정 정지 위험. 도메인 워밍업·이메일 모범 사례 준수 필요.

이메일 반송 처리 방법은?

bounced 웹훅 수신 → 하드 반송은 영구 삭제, 소프트 반송은 재시도. 반송률 5% 이상이면 발신자 평판 저하.

마케팅 이메일 vs 트랜잭션 이메일?

트랜잭션: 개별 행동 트리거된 단일 이메일.

마케팅: 다수 수신자 대상 캠페인.

Brevo는 이 둘을 분리 처리.

구독 취소 링크 추가법?

마케팅 이메일은 자동, 트랜잭션 이메일엔 직접 추가:

<a href="{{ unsubscribe_url }}">Unsubscribe</a>
Enter fullscreen mode Exit fullscreen mode

내 도메인에서 전송 가능?

네. SPF, DKIM, DMARC 레코드 설정 필요. Brevo 대시보드 → 발신자 & IP에서 값 확인.

특정 시간대 예약 발송은?

scheduleAt에 ISO 8601 타임스탬프 사용:

{
  "scheduledAt": "2026-03-25T09:00:00-05:00"
}
Enter fullscreen mode Exit fullscreen mode

전송량 제한 초과 시?

429 에러 발생. 응답의 X-RateLimit-Reset으로 재시도 타이밍 확인, 백오프 로직 및 대기열 적용 권장.

Top comments (0)