Mail Send API로 이메일 보내기

Mail Send API로 이메일 보내기

이메일을 보낼 때 코드에서 직접 SMTP 서버를 다루거나 발송 서버를 띄우는 대신, SendGrid의 v3 Web API가 제공하는 Mail Send 엔드포인트에 HTTP 요청만 던지면 돼요. 발신자·수신자·제목·본문 같은 기본 요소는 물론, 개인별 설정(personalizations)·첨부파일·동적 템플릿까지 JSON 객체 하나로 지정할 수 있어요. 여기선 이 발송 엔드포인트의 쓰는 법과 놓치기 쉬운 제약을 정리할게요.

출처: Mail Send API Overview — SendGrid Docs

기준 URL

SendGrid의 v3 Web API는 지역에 따라 호출 주소가 달라져요.

  • 글로벌 사용자·서브유저: https://api.sendgrid.com
  • EU 지역 서브유저: https://api.eu.sendgrid.com

발송은 이 기준 도메인 아래 POST /v3/mail/send로 이뤄져요.

발송 개념과 활용

시간대를 고른 발송 (Schedule a send)

여유가 있다면 이메일은 한가한 시간대(off-peak)로 맞춰 보내는 게 좋아요. 대부분의 이메일이 정시(11:00)나 30분 단위로 몰리거든요. 11:00 대신 10:53처럼 정각을 살짝 비켜서 보내면 한가한 시간대의 트래픽이 줄어들어 지연(deferral) 확률이 낮아져요.

동적 템플릿과 Handlebars

본문에 평문 텍스트나 원시 HTML을 바로 넘기는 대신, **동적 템플릿(Dynamic Templates)**을 사용할 수도 있어요. 템플릿과 동적 데이터를 이메일에 넣는 방법은 '동적 템플릿으로 이메일 보내기' 문서에서 확인할 수 있어요.

Mail Body Compression (본문 압축)

고용량 계정 일부에는 본문 압축을 쓸 수 있어요. Mail Send 엔드포인트에 정의된 JSON 페이로드를 만든 뒤 gzip으로 압축(gzip 파일은 30MB 이하)해서 보내는 방식이에요. 이때 JSON 페이로드 안의 첨부파일까지 함께 압축되고, 압축된 데이터도 헤더·본문·첨부를 합쳐 30MB 이내여야 해요.

사용 순서를 보면 이래요.

  1. 고객지원에 요청을 넣어 계정에 gzip을 활성화해요.
  2. gzip이 켜지면 Content-Encoding 헤더를 gzip 값으로 추가해요. (Content-Encoding: gzip)
  3. gzip을 data-binary로 보내요. (--data-binary '@data.json.gz')

여러 Reply-To 주소

reply_to_list를 쓰면 수신자가 회신(답장)을 받을 주소를 하나 이상 지정할 수 있어요. 다만 몇 가지 조건이 있어요.

  • reply_to와 reply_to_list는 상호 배타적이에요. 둘 다 쓰면 API 호출이 거부돼요.
  • reply_to_list 객체는 최소한 email 속성은 있어야 하고, name 속성도 함께 넣을 수 있어요.
  • reply_to_list의 각 이메일 주소는 유일해야 해요.
  • Mail Send 요청당 reply_to_list 이메일은 1,000개까지만 가능해요.
  • SMTP 호출에서는 유효하지 않은 이메일을 제외하고 보내요.

제약 (Limitations)

v3 Mail Send 엔드포인트를 쓸 때 알고 있어야 할 제한이에요.

  • 첨부를 포함한 이메일 전체 크기는 30MB 미만이어야 해요.
  • 총 수신자는 1,000명을 넘어선 안 돼요. personalizations 배열 안의 각 객체에 정의된 to·cc·bcc 수신자를 모두 합한 값이에요.
  • 커스텀 인자(custom args)의 총 길이는 10,000바이트 미만이어야 해요.
  • from 필드에는 유니코드 인코딩을 지원하지 않아요.

파라미터별 자세한 요구사항과 제한은 Mail Send 엔드포인트 문서를 참고하세요.

검증 (Validation)

v3 Mail Send 엔드포인트에 요청을 보내면 본문이 실제 전송 전에 먼저 검증돼요. 오류가 있으면 SendGrid가 요청별로 가능한 한 많은 문제를 찾아 돌려줘요. 자세한 건 오류 문서를 읽어보세요.

더 알아보기