> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendbaze.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send emails with Node.js

> Learn how to send your first email using the Sendbaze Node.js SDK.

## Prerequisites

Before you start, you need:

* A Sendbaze [API key](https://docs.sendbaze.com/get-started/create-api-key.md)
* A [verified domain](https://docs.sendbaze.com/get-started/add-domain.md). A test key works without one, and so does the [shared test address](https://docs.sendbaze.com/get-started/test-without-a-domain.md) for emails to yourself.

## Guide

**1. Install**

Get the Sendbaze SDK. It is a zero-dependency client built on `fetch` and runs on Node.js 20+, Bun, Deno, Cloudflare Workers and Vercel Edge.

```bash npm theme={"dark"}
npm install @sendbaze/sdk
```

```bash pnpm theme={"dark"}
pnpm add @sendbaze/sdk
```

```bash yarn theme={"dark"}
yarn add @sendbaze/sdk
```

```bash bun theme={"dark"}
bun add @sendbaze/sdk
```

**2. Set your API key**

Store the key in an environment variable in your `.env` file.

```bash .env theme={"dark"}
SENDBAZE_API_KEY=sk_live_xxxxxxxx
```

**3. Send an email**

```ts send.ts theme={"dark"}
import { Sendbaze } from "@sendbaze/sdk";

const sendbaze = new Sendbaze({ apiKey: process.env.SENDBAZE_API_KEY! });

const { id } = await sendbaze.emails.send({
  from: "Yourshop <orders@yourshop.co.za>",
  to: "thandi@example.com",
  subject: "Your order #1042 has shipped",
  html: "<p>Tracking: <b>CG123456789ZA</b></p>",
});

console.log(id); // em_01j9...
```

The call returns as soon as the email is queued. Delivery happens in the background and is reported by [webhook](https://docs.sendbaze.com/learn/webhooks/overview.md) and in the dashboard **Logs**.

**4. Try it**

Run the file and check the **Logs** page. With a live key the email arrives within seconds; with a test key it appears in the logs with a test badge and is never delivered.

## Examples

### Handle errors

Every non-2xx response throws a `SendbazeError` with a stable `code` that matches the [errors reference](https://docs.sendbaze.com/errors.md). Network failures throw `SendbazeConnectionError`, which is safe to retry with the same idempotency key.

```ts theme={"dark"}
import { Sendbaze, SendbazeError } from "@sendbaze/sdk";

const sendbaze = new Sendbaze({ apiKey: process.env.SENDBAZE_API_KEY! });

try {
  await sendbaze.emails.send(
    { from: "orders@yourshop.co.za", to: "thandi@example.com", subject: "Hi", text: "Hello" },
    { idempotencyKey: "order-1042-shipped" },
  );
} catch (error) {
  if (error instanceof SendbazeError) {
    console.error(error.code, error.fields, error.requestId);
  } else {
    throw error;
  }
}
```

### Send with a template

```ts theme={"dark"}
await sendbaze.emails.send({
  from: "orders@yourshop.co.za",
  to: "thandi@example.com",
  templateId: "tpl_01j9x7k2r4m8q3v5n6b7c8d9e0",
  variables: { name: "Thandi", order_id: 1042, eta: "Friday" },
});
```

### Attach a file

```ts theme={"dark"}
import { readFile } from "node:fs/promises";

const invoice = await readFile("./invoice-1042.pdf");

await sendbaze.emails.send({
  from: "orders@yourshop.co.za",
  to: "thandi@example.com",
  subject: "Invoice 1042",
  html: "<p>Your invoice is attached.</p>",
  attachments: [
    { filename: "invoice-1042.pdf", contentType: "application/pdf", content: invoice.toString("base64") },
  ],
});
```

### Send a React component

Prefer components to HTML strings? Install `@react-email/render react react-dom`, then pass `react` instead of `html`. The SDK renders the HTML and a plain-text part before sending. See [React Email](https://docs.sendbaze.com/learn/sending/react-email.md).

```tsx theme={"dark"}
import { OrderShipped } from "./emails/order-shipped";

await sendbaze.emails.send({
  from: "orders@yourshop.co.za",
  to: "thandi@example.com",
  subject: "Your order #1042 has shipped",
  react: <OrderShipped name="Thandi" tracking="CG123456789ZA" />,
});
```

### Look up a message

```ts theme={"dark"}
const message = await sendbaze.emails.get("em_01j9...");
console.log(message.status); // "queued" | "sent" | "delivered" | "bounced" | ...
for (const event of message.events) console.log(event.type, event.occurredAt);
```

> [card] [SDK reference](https://docs.sendbaze.com/resources/sdks.md)
>
> Every resource the SDK covers: emails, templates, domains, suppressions, webhooks, SMS and usage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.