리센드 API 키 발급받고 첫 이메일 보내는 방법

Resend는 개발자를 위해 만들어진 이메일 API입니다: 하나의 POST 요청, 하나의 JSON 본문만으로 트랜잭션 이메일을 발송할 수 있습니다. 모든 요청에는 API 키가 필요하며, 키를 생성하는 방식에 따라 유출되었을 때 발생할 수 있는 피해 정도가 결정됩니다. 이 가이드는 전체 과정을 안내합니다: 회원 가입, 발신 도메인 확인 (또는 내장된 테스트 주소 사용), 올바른 권한 범위로 키 생성, 그리고 curl, Node, Python을 사용하여 첫 이메일 발송. 또한, Apidog에 키를 저장하여 셸에 비밀을 붙여넣지 않고도 엔드포인트를 테스트할 수 있습니다.

API가 발송 외에 어떤 기능을 하는지 전반적인 내용을 알고 싶다면, Resend API 초보자 가이드에서 나머지 내용을 다룹니다. 아래의 모든 내용은 공식 Resend 문서와 대조하여 확인되었으므로, 숫자 및 오류 문자열이 실제로 보이는 것과 일치할 것입니다.

버튼

시작하기 전에 필요한 것

Resend 계정. 이 튜토리얼에는 무료 요금제로 충분합니다.
귀하가 소유한 도메인. 바로 사용할 수 없다면, 테스트 주소로 첫 발송을 진행할 수 있습니다.
컴퓨터에 curl, SDK 예제를 원하면 Node.js 또는 Python.
테스트 섹션을 따를 계획이라면 Apidog 설치.

1단계: Resend 계정 생성

resend.com에서 가입하고 이메일을 확인하세요. 가입 시 사용한 주소를 기록해 두세요: 도메인을 확인하기 전까지는 Resend가 테스트 이메일을 발송할 수 있는 유일한 수신함이며, 이를 잊으면 첫날 가장 혼란스러운 403 오류를 보게 될 것입니다.

2단계: 발신 도메인 확인 또는 테스트 주소 사용

두 가지 방법이 있습니다; 빠른 방법부터 시작하세요.

방법 A: 온보딩 테스트 주소. Resend는 설정 없이 onboarding@resend.dev에서 이메일을 발송할 수 있도록 합니다. 단, 수신자는 본인 계정의 이메일 주소여야 합니다. 다른 사람에게 발송하면 API는 "You can only send testing emails to your own email address"(자신 이메일 주소로만 테스트 이메일을 보낼 수 있습니다)라는 메시지와 함께 403 오류를 반환합니다.

방법 B: 본인 도메인. 실제 사용을 위해서는 대시보드의 'Domains' 아래에 도메인을 추가하세요. Resend는 루트 도메인 대신 notifications.example.com과 같은 서브도메인을 권장합니다. 이는 제품의 발신 평판이 회사 이메일과 분리되도록 하기 위함입니다. 수신자에게 가장 가까운 지역을 선택한 다음, Resend가 생성하는 DNS 레코드를 DNS 제공업체에 복사하세요. 문서는 이를 "DKIM 및 SPF 구성(TXT 및 MX 또는 CNAME 레코드)"으로 설명합니다. 반송 경로(Return-Path) 서브도메인은 기본적으로 send.example.com입니다.

DNS 전파는 최대 72시간이 걸릴 수 있지만, 일반적으로 확인은 15분 이내에 완료됩니다. 확인이 지연되면 두 가지 일반적인 원인을 확인하세요: send 서브도메인 대신 루트에 배치된 레코드, 그리고 Cloudflare 프록싱(클라우드 아이콘이 주황색이 아닌 회색이어야 합니다). 레코드를 수정한 다음 "확인 재시작"을 클릭하세요. 이후 DMARC 레코드를 추가하세요; 발송에는 필수 사항이 아니지만, 받은 편지함 제공업체는 이를 권장합니다.

3단계: 올바른 범위로 API 키 생성

대시보드에서 API 키 페이지를 열고 API 키 생성을 클릭하세요. 세 가지 필드가 중요하며, API 키 생성 문서에서 각 필드를 다룹니다:

이름. 최대 50자. 나중에 키를 쉽게 구분할 수 있도록 billing-service-prod와 같이 앱 및 환경에 맞춰 이름을 지정하세요.
권한. "전체 액세스"는 도메인 및 다른 API 키를 포함하여 모든 리소스를 생성, 삭제, 조회, 업데이트할 수 있습니다. "발송 액세스"는 이메일만 발송할 수 있습니다. 배포되는 모든 것에는 발송 액세스를 선택하세요. 전체 액세스 키는 노트북에 있거나 아예 존재하지 않아야 합니다.
도메인. 발송 액세스를 사용하면 키를 하나의 확인된 도메인으로 제한할 수 있습니다. notifications.example.com에 범위가 지정된 키는 billing.example.com에서 발송할 수 없으므로, 유출 시 피해 범위를 제한할 수 있습니다.

Resend는 키를 단 한 번만 보여줍니다. 키는 re_로 시작하며, 대화 상자를 닫으면 키 이름을 변경할 수는 있지만 다시 볼 수는 없습니다. 환경 변수에 바로 복사하세요:

export RESEND_API_KEY="re_xxxxxxxxx"

Resend 자체 가이드: 키는 만료되지 않으므로 90일 또는 그 이전에 교체하세요; 대시보드는 30일 동안 사용되지 않은 키에 플래그를 지정합니다; 그리고 키가 유출되면 다음 교체를 기다리지 말고 즉시 삭제하세요. git에 re_ 문자열을 커밋하는 것이 가장 흔한 유출 경로이므로, 첫 푸시 전에 리포지토리에 시크릿 스캐너를 실행하세요.

POST https://api.resend.com/api-keys를 사용하여 name, permission(full_access 또는 sending_access) 및 선택적 domain_id를 전달하여 키를 생성할 수도 있습니다. 이 호출에는 전체 액세스 키가 필요합니다. 이는 전체 액세스 키를 하나만 유지해야 하는 또 다른 이유입니다.

4단계: 첫 이메일 발송

발송 엔드포인트는 POST https://api.resend.com/emails입니다. 인증은 Authorization 헤더의 Bearer 토큰이며, 본문은 JSON이고 HTTPS만 허용됩니다. from, to, subject 세 가지 필드가 필수입니다. html, text 중 하나 또는 둘 다 추가할 수 있습니다. html만 발송하면 Resend가 일반 텍스트 부분을 생성합니다. to는 문자열 또는 최대 50개의 주소 배열을 받습니다. 전체 파라미터 목록은 이메일 발송 참조에 있습니다.

curl

curl -X POST 'https://api.resend.com/emails' \
  -H "Authorization: Bearer $RESEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <onboarding@resend.dev>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>"
  }'

성공적인 호출은 {"id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"}를 반환합니다. 한 가지 특이사항: 모든 요청에는 User-Agent 헤더가 포함되어야 합니다. 그렇지 않으면 API가 코드 1010과 함께 403을 응답합니다. curl과 SDK는 이를 설정하지만, 엣지 런타임의 직접 제작 클라이언트는 그렇지 않을 수 있습니다.

Node.js

npm install resend

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

const { data, error } = await resend.emails.send({
  from: 'Acme <notifications@example.com>',
  to: ['you@yourcompany.com'],
  subject: 'First Resend email',
  html: '<p>Your Resend key works.</p>',
});

if (error) {
  console.error(error);
} else {
  console.log(data.id);
}

Node SDK는 API 오류에 대해 예외를 발생시키지 않습니다. { data, error }를 반환하므로, data.id를 사용하기 전에 error를 확인하세요.

Python

pip install resend

import os
import resend
from resend.exceptions import ResendError

resend.api_key = os.environ["RESEND_API_KEY"]

params: resend.Emails.SendParams = {
    "from": "Acme <notifications@example.com>",
    "to": ["you@yourcompany.com"],
    "subject": "First Resend email",
    "html": "<p>Your Resend key works.</p>",
}

try:
    email = resend.Emails.send(params)
    print(email["id"])
except ResendError as err:
    print(err)

Python SDK는 반대로 실패 시 ResendError를 발생시키므로, 발송 코드를 try/except로 감싸야 합니다.

5단계: Apidog에 키 저장 및 테스트

Curl은 키가 한 번 작동한다는 것을 증명합니다. Apidog는 일회성 테스트를 팀이 다시 실행할 수 있는 것으로 만들고, 키를 셸 기록 및 채팅 로그에서 보호합니다.

키를 비밀 변수로 저장하세요. Resend라는 환경을 생성하고, RESEND_API_KEY를 변수로 추가한 다음, UI에서 값이 마스킹되고 내보내기에서 제외되도록 비밀로 표시하세요. 환경 및 비밀 변수 가이드는 환경별로 다른 발송 전용 키를 유지하는 경우(그렇게 해야 합니다) 개발, 스테이징, 프로덕션 환경 분할에 대해 다룹니다.

요청을 발송하세요. https://api.resend.com/emails로 POST 요청을 생성하고, Auth를 {{RESEND_API_KEY}}를 사용하는 Bearer Token으로 설정한 후, curl 예제에서 JSON 본문을 붙여넣으세요. 발송을 클릭하세요. id는 아래에서 다룰 비율 제한 헤더 옆의 응답 패널에 표시됩니다.

테스트로 저장하세요. 두 가지 검증을 추가하세요: 상태 코드가 200이고 $.id가 존재하는지. 요청을 테스트 시나리오에 넣으면 이메일 코드를 건드릴 때마다 실행되는 스모크 테스트가 됩니다. 도메인으로 제한된 발송 키를 사용하여 스테이징 환경을 대상으로 지정하면 CI에서 안전하게 실행할 수 있습니다.

프론트엔드 작업을 위해 엔드포인트를 모의하세요. 프론트엔드는 실제 발송이 아닌 응답 형태를 필요로 합니다. Apidog에서 엔드포인트를 모의하여 모든 호출에 {"id": "mock-email-id"}를 반환하도록 하세요. UI 팀은 하루 100개 무료 할당량을 소진하거나 실제 받은 편지함을 스팸으로 채우지 않고도 하루 종일 "이메일 발송됨" 상태를 만들 수 있습니다. 이를 설정하려면 Apidog를 다운로드하세요; 무료 플랜은 4명의 사용자를 지원합니다.

가장 먼저 도달할 무료 등급 제한

Resend 가격 페이지에는 무료 플랜이 월 3,000개의 이메일(일일 100개 제한), 3개 도메인, 30일 데이터 보존으로 명시되어 있습니다. Pro 플랜은 월 $20부터 시작하여 50,000개의 이메일, 10개 도메인, 일일 제한 없음이며, 초과 사용 시 1,000개 이메일당 $0.90입니다.

resend.dev 주소로 보내는 테스트 이메일도 할당량에 포함되므로, delivered@resend.dev를 대상으로 하는 부하 테스트는 여전히 일일 100개 제한을 소모합니다. bounced@resend.dev, complained@resend.dev, suppressed@resend.dev는 실제 유효하지 않은 주소 없이 하드 바운스, 스팸 불만 및 수신 거부된 수신자를 시뮬레이션합니다.

할당량과는 별개로, 비율 제한은 팀당 초당 10개 요청으로 기본 설정되며, 팀의 모든 키에서 공유됩니다. 각 응답에는 ratelimit-limit, ratelimit-remaining, ratelimit-reset 및 retry-after 헤더가 포함되므로, 발송 루프는 429 오류에 도달하기 전에 물러날 수 있습니다. 더 필요하세요? Resend는 추가 팀을 생성하는 대신 지원팀에 문의할 것을 요청합니다.

일반적인 오류 및 해결 방법

모든 실패는 statusCode, name, message를 포함한 JSON으로 반환됩니다. 다음은 오류 참조에서 발췌한, 첫날에 만날 수 있는 오류들입니다:

상태	이름	발생한 문제	해결책
401	`missing_api_key`	`Authorization` 헤더 없음	`Authorization: Bearer re_...` 추가
401	`restricted_api_key`	발송 전용 키가 발송 외 엔드포인트에 사용됨	해당 호출에 전체 액세스 키 사용
403	`validation_error`	"도메인이 확인되지 않았습니다"	DNS 확인을 완료하거나 `from` 주소 수정
403	`validation_error`	테스트 주소가 본인 외 다른 사람에게 발송됨	본인 계정 이메일로 발송하거나 도메인 확인
403	`restricted_api_key`	"API 키가 활성화되지 않았습니다"	키가 삭제되었습니다; 새 키 생성
422	`missing_required_field`	`from`, `to`, 또는 `subject` 누락	참조 문서를 기준으로 본문 확인
429	`rate_limit_exceeded`	초당 10개 이상의 요청	발송 대기열 처리, `retry-after` 헤더 준수
429	`daily_quota_exceeded`	무료 플랜에서 일일 100개 이메일 초과	재설정까지 기다리거나 업그레이드

올바르다고 확신하는 키로 401 오류가 발생하면 일반적으로 변수에 후행 개행 문자가 있거나 .env 파일이 로드되지 않았음을 의미합니다. 둘 다 API 측에서는 키가 누락된 것처럼 보입니다.

자주 묻는 질문

Resend API 키를 생성한 후 다시 볼 수 있나요?

아니요. Resend는 생성 시 한 번만 값을 보여줍니다. 분실했다면, 동일한 이름과 권한으로 새 키를 생성하고 배포한 다음, 이전 키를 삭제하세요.

전체 액세스 또는 발송 액세스 중 무엇을 선택해야 하나요?

컴퓨터를 벗어나는 모든 키에는 하나의 도메인으로 제한된 발송 액세스를 사용하세요. 도메인 추가 또는 다른 키 생성과 같은 대시보드 스타일 작업을 위해서는 하나의 전체 액세스 키를 유지하고, 절대로 앱에 포함하여 배포하지 마세요.

도메인을 확인하지 않고도 발송 테스트를 할 수 있나요?

네. onboarding@resend.dev를 from 주소로 사용하고 본인 계정 이메일을 수신자로 사용하세요. 도메인이 확인될 때까지 다른 수신자는 403 오류를 반환합니다.

대시보드 대신 터미널에서 Resend를 관리하는 방법이 있나요?

네. Resend CLI 가이드는 브라우저를 열지 않고도 설치 방법과 일반적인 도메인 및 이메일 명령 실행 방법을 다룹니다.

무료 플랜에서 하루 100개 이메일을 초과하면 어떻게 되나요?

API는 daily_quota_exceeded와 함께 429 오류를 반환하며, 발송은 일일 재설정 후 다시 시작됩니다. 정기적으로 더 많은 양이 필요하다면, Pro 플랜은 제한을 없애고 무료 이메일 API 비교에서 다른 공급업체의 무료 등급을 비교한 내용을 보여줍니다.

마무리

Resend API 키를 얻는 데는 2분, 제대로 설정하는 데는 5분이 걸립니다. 서브도메인을 확인하고, 해당 도메인에 고정된 발송 전용 키를 생성하고, 환경 변수에 보관하고, curl로 이메일 하나를 발송하여 왕복을 확인하세요. 그런 다음 Apidog로 요청을 옮기고, 검증을 저장하고, 엔드포인트를 모의하여 팀의 나머지 구성원이 할당량을 소진하지 않고도 이를 기반으로 개발할 수 있도록 하세요. 여전히 제 역할을 하는 가장 적은 권한의 키를 배포하세요.

버튼