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

# TypeScript / Node.js SDK

> Install wazobiamail from npm and send transactional email from Node.js 18+, Bun, Deno, Cloudflare Workers or Vercel Edge.

The official TypeScript SDK is a typed, zero-production-dependency client for the WazobiaMail API. It ships ESM and CommonJS builds and works anywhere with native `fetch`, `FormData` and `Blob`.

> [card] [npm package](https://www.npmjs.com/package/wazobiamail)
>
> `wazobiamail` — version 0.1.0

> [card] [Source](https://github.com/WazobiaMail/wazobiamail-node)
>
> WazobiaMail/wazobiamail-node

## At a glance

| | |
| - | - |
| Runtime | Node.js 18+, Bun, Deno, Cloudflare Workers, Vercel Edge |
| Language | TypeScript 5+, JavaScript |
| Package | `wazobiamail` |
| Install | `npm install wazobiamail` |
| Auth | `X-API-Key` by default, or Bearer access token |
| Source | [github.com/WazobiaMail/wazobiamail-node](https://github.com/WazobiaMail/wazobiamail-node) |

## Install

```bash theme={null}
npm install wazobiamail
# or
bun add wazobiamail
# or
pnpm add wazobiamail
```

## Configure

The key can be passed directly or read from `WAZOBIA_API_KEY` / `WAZOBIAMAIL_API_KEY`.

```ts theme={null}
import { WazobiaMail } from 'wazobiamail';

const client = new WazobiaMail({
  apiKey: process.env.WAZOBIA_API_KEY!,
  timeout: 15_000,
});
```

## Send your first email

```ts theme={null}
const receipt = await client.send({
  from: 'Acme <hello@mail.example.com>',
  to: 'customer@example.com',
  subject: 'Your order shipped',
  html: '<p>Your order is on its way.</p>',
  text: 'Your order is on its way.',
}, {
  idempotencyKey: 'order-1042-shipped',
});

console.log(receipt.data.result.trackingId);
```

URL attachments are supported directly:

```ts theme={null}
await client.messages.send({
  to: 'billing@example.com',
  subject: 'Invoice #1042',
  html: '<p>Invoice attached.</p>',
  attachments: [
    { url: 'https://cdn.example.com/1042.pdf', fileName: 'invoice-1042.pdf' },
  ],
});
```

## What you can do

* Send transactional email with HTML, text, CC/BCC, reply-to and idempotency keys.
* Upload attachments or send inline files through the multipart endpoint.
* Create and verify sending domains, read DNS records and drive Cloudflare DNS.
* Provision hosted mailboxes, credentials and enterprise headless inboxes.
* Run spam/deliverability checks and read tracking events.
* Manage sending API keys, SMTP relays, billing invoices, plans, credits and support tickets.

## Framework notes

The core SDK has no Node-only production dependencies, so it runs on edge runtimes. In browser code, never expose an API key — proxy requests through your server. For framework helpers, use `wazobiamail-vue` or `wazobiamail-nuxt` instead of wiring composables yourself.

## Errors and retries

The client throws typed errors: `WazobiaAuthenticationError`, `WazobiaForbiddenError`, `WazobiaNotFoundError`, `WazobiaValidationError`, `WazobiaRateLimitError`, `WazobiaTimeoutError` and generic `WazobiaApiError`.

```ts theme={null}
import { WazobiaRateLimitError } from 'wazobiamail';

try {
  await client.send(message);
} catch (error) {
  if (error instanceof WazobiaRateLimitError) {
    console.error('Retry after', error.retryAfter, 'seconds');
  }
  throw error;
}
```

Retry only idempotent sends, and reuse the same `idempotencyKey` when retrying.

## Links

* [npm](https://www.npmjs.com/package/wazobiamail)
* [GitHub](https://github.com/WazobiaMail/wazobiamail-node)
* [Full README](https://github.com/WazobiaMail/wazobiamail-node#readme)
* [All official SDKs](https://docs.wazobiamail.com/docs/guides/sdks.md)


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