Setup and Installation
Relevant source files
The following files were used as context for generating this wiki page:
The Resend Node.js SDK provides a library for interacting with the Resend API. It enables developers to send emails using HTML or React components, manage contacts, and handle webhooks within Node.js environments. This documentation covers the requirements, installation procedures, and initial configuration needed to integrate the SDK into a project.
Requirements and Prerequisites
The Resend Node.js SDK requires Node.js version 20 or higher to function correctly. Development tasks, such as running scripts or builds, prefer Node.js version 22.12.0 or higher.
Sources: package.json:10-17
Before installing the SDK, you must obtain an API key from the Resend Dashboard. To send emails from a custom domain, you must verify that domain in the Resend Dashboard.
Sources: readme.md:44-46, readme.md:61-63
Installation
You can install the SDK using standard package managers. The library is distributed as the resend package.
Standard Installation
Install the package using npm or yarn:
npm install resend
# or
yarn add resend
Sources: readme.md:31-35
Peer Dependencies
The SDK supports sending emails via React templates. If you intend to use the react property in email or template methods, you must install @react-email/render as a peer dependency.
Sources: package.json:59-67, src/templates/templates.spec.ts:167-170
Initial Configuration
To use the SDK, you must instantiate the Resend class with your API key.
Authentication Flow
The Resend constructor accepts an API key as its first argument. If you do not provide a key directly, the SDK attempts to read the RESEND_API_KEY environment variable.
The SDK sets the Authorization header as Bearer <API_KEY> for all subsequent requests.
Sources: src/resend.ts:74-98, readme.md:48-50
SDK Options
You can provide an optional ResendOptions object as the second argument to the constructor to customize the base URL or the user agent.
| Option | Type | Default | Description |
|---|---|---|---|
baseUrl | string | https://api.resend.com | The root URL for API requests. Can be overridden by RESEND_BASE_URL env var. |
userAgent | string | resend-node:<version> | The User-Agent header value. Can be overridden by RESEND_USER_AGENT env var. |
Sources: src/resend.ts:51-72, src/resend.ts:100-101
Development and Build Scripts
If you are contributing to the SDK or building it from source, use the following pnpm scripts defined in the project configuration.
| Script | Command | Purpose |
|---|---|---|
build | tsdown src/index.ts --format esm,cjs --dts | Transpiles TypeScript to ESM and CJS formats. |
test | vitest run --exclude e2e | Runs unit tests. |
test:e2e | vitest run e2e | Runs end-to-end integration tests (e.g., Next.js, esbuild). |
lint | biome check . | Performs code linting using Biome. |
Sources: package.json:28-40
E2E Integration Testing
The project includes end-to-end (e2e) tests to verify compatibility with frameworks like Next.js and bundlers like esbuild. The e2e suite builds the SDK and then installs it into temporary integration projects using absolute paths to the local build.
Sources: e2e/e2e.spec.ts:11-23, e2e/e2e.spec.ts:34-53
Summary
Setting up the Resend Node.js SDK involves installing the resend package via a package manager and initializing the Resend class with a valid API key. Configuration can be managed through constructor parameters or environment variables. For React-based email rendering, ensure the optional @react-email/render peer dependency is present in your environment.