send

Resend API 이메일 전송

Resend의 POST /emails 엔드포인트를 통해 이메일을 한 통 보내는 방법을 설명할게요. from(발신자), to(수신자), subject(제목) 정도만 지정하면 바로 이메일을 보낼 수 있답니다. 본문은 HTML이나 일반 텍스트(text)로 작성할 수 있고, 필요하면 참조(replyTo), 첨부 파일(attachments), 예약 발송(scheduledAt), 태그(tags) 같은 다양한 옵션도 함께 활용할 수 있어요.

오늘은 Node.js, Python, cURL, CLI 등 각 언어별로 실제 사용 예시를 확인하고, 주요 파라미터도 정리해 볼게요.

출처: 문서

본문

기본 사용 예시

대표적으로 데모용 도메인([email protected])으로 보내는 가장 간단한 예시예요. API 키 re_xxxxxxxxx 자리에 본인 키를 넣으면 됩니다.

Node.js

import { Resend } from 'resend';

const resend = new Resend('re_xxxxxxxxx');

const { data, error } = await resend.emails.send({
  from: 'Acme <[email protected]>',
  to: ['[email protected]'],
  subject: 'hello world',
  html: '<p>it works!</p>',
});

Python

import resend

resend.api_key = "re_xxxxxxxxx"

params: resend.Emails.SendParams = {
  "from": "Acme <[email protected]>",
  "to": ["[email protected]"],
  "subject": "hello world",
  "html": "<p>it works!</p>"
}

email = resend.Emails.send(params)
print(email)

cURL

curl -X POST 'https://api.resend.com/emails' \
     -H 'Authorization: Bearer re_xxxxxxxxx' \
     -H 'Content-Type: application/json' \
     -d $'{
  "from": "Acme <[email protected]>",
  "to": ["[email protected]"],
  "subject": "hello world",
  "html": "<p>it works!</p>"
}'

CLI

resend emails send \
  --from "Acme <[email protected]>" \
  --to [email protected] \
  --subject "hello world" \
  --html "<p>it works!</p>"

응답 (Response)

{
  "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
}

주요 파라미터

파라미터	타입	필수	설명
`from`	string	필수	발신자 이메일 주소. 친근한 이름을 포함하려면 `Name <[email protected]>` 형태로, 예: `Acme <[email protected]>`
`to`	string \| string[]	필수	수신자 이메일 주소. 여러 주소는 문자열 배열로 보내며 최대 50개
`subject`	string	필수	이메일 제목
`bcc`	string \| string[]	선택	숨은 참조 수신자, 여러 주소는 배열로
`cc`	string \| string[]	선택	참조 수신자, 여러 주소는 배열로
`scheduledAt`	string	선택	예약 발송 시간. 자연어(`in 1 min`) 또는 ISO 8601 형식(`2026-08-05T11:52:01.858Z`)
`replyTo`	string \| string[]	선택	회신 받을 주소, 여러 주소는 배열로
`html`	string	선택	이메일의 HTML 버전
`text`	string	선택	이메일의 일반 텍스트 버전. 제공하지 않으면 HTML로 텍스트 버전을 자동 생성하고, 빈 문자열로 두면 자동 생성도 끌 수 있어요
`react`	React.ReactNode	선택	메시지를 작성할 React 컴포넌트 (Node.js SDK에서만 사용 가능)
`headers`	object	선택	이메일에 추가할 커스텀 헤더
`attachments`	array	선택	첨부 파일의 파일명과 내용 (Base64 인코딩 후 이메일당 최대 40MB)
`tags`	array	선택	키/값 쌍으로 전달하는 커스텀 데이터
`template`	object	선택	템플릿을 사용해 보낼 때 지정. `id`와 `variables`를 포함

첨부 파일 (attachments)

첨부 항목마다 다음과 같은 속성을 지정할 수 있어요.

content: 첨부 파일의 내용, buffer 또는 Base64 문자열
filename: 첨부 파일 이름
path: 첨부 파일이 호스팅된 경로
contentType: 첨부 파일의 콘텐츠 타입, 지정하지 않으면 filename에서 자동 유추
contentId: 이메일에 이미지를 삽입할 때 사용. 이미지를 보여주려면 HTML의 img 태그 src에 ID를 넣어야 해요 (예: <img src="cid:...">)

태그 (tags)

태그의 name과 value는 둘 다 필수예요.

ASCII 문자(a–z, A–Z), 숫자(0–9), 밑줄(_), 하이픈(-)만 사용 가능
최대 256자까지 허용

템플릿 (template)

템플릿으로 보낼 때는 template 객체에 다음을 지정해요.

id: 게시된 템플릿의 id 또는 alias
variables: 변수별 키를 가진 객체 (필요한 경우)

template을 제공하면 payload에 html, text, react를 함께 보낼 수 없어요. 함께 보내면 API가 검증 오류를 반환합니다. 템플릿을 쓸 때 from, subject, reply_to의 payload 값이 템플릿 기본값보다 우선 적용되고, 템플릿이 기본값을 제공하지 않으면 payload에서 반드시 지정해야 해요.

변수 예시:

variables: {
	CTA: 'Sign up now',
	CTA_LINK: 'https://example.com/signup'
}

템플릿의 HTML을 파싱해서 사용된 변수가 모두 제공된 경우에만 이메일이 발송되고, 빠진 변수가 있으면 검증 오류가 발생합니다. 변수 key는 ASCII 문자/숫자/밑줄만 사용 가능하며 최대 50자예요. FIRST_NAME, LAST_NAME, EMAIL, UNSUBSCRIBE_URL은 예약어라 사용할 수 없어요. 값의 제한은 문자열 2,000자, 숫자는 2^53 - 1 이하랍니다.

헤더 (Headers)

Idempotency-Key: 중복 이메일을 방지하는 멱등성 키예요. API 요청마다 고유해야 하고, 24시간 후 만료되며, 최대 256자까지 허용돼요.

더 알아보기 (Learn more)

공식 문서