> ## 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.

# Nuxt 3 & 4 Module

> Install wazobiamail-nuxt to send from Nitro routes and use auto-imported Vue composables with server-only API keys.

`wazobiamail-nuxt` is the official Nuxt module. It keeps the API key in private Nitro runtime config, adds a `serverWazobiaClient(event)` helper for server routes, and auto-imports the Vue composables from `wazobiamail-vue`.

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

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

## At a glance

| | |
| - | - |
| Runtime | Nuxt 3 or Nuxt 4 |
| Package | `wazobiamail-nuxt` |
| Install | `npm install wazobiamail-nuxt` |
| Secret handling | Private `runtimeConfig.wazobiamail.apiKey` |
| Source | [github.com/WazobiaMail/wazobiamail-nuxt](https://github.com/WazobiaMail/wazobiamail-nuxt) |

## Install

```bash theme={null}
npm install wazobiamail-nuxt
```

```ts theme={null}
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['wazobiamail-nuxt'],
  wazobiamail: {
    apiKey: process.env.WAZOBIA_API_KEY,
    baseUrl: process.env.WAZOBIA_BASE_URL, // optional
    timeout: 30_000, // milliseconds
  },
});
```

The module writes:

* `runtimeConfig.wazobiamail.apiKey` — private, server-only.
* `runtimeConfig.wazobiamail.baseUrl` and `timeout` — private, server-only.
* `runtimeConfig.public.wazobiamail.baseUrl` — safe to expose.

## Send from a Nitro route

`serverWazobiaClient(event)` is auto-imported inside `server/`:

```ts theme={null}
// server/api/send.post.ts
export default defineEventHandler(async (event) => {
  const client = serverWazobiaClient(event);

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

  return { trackingId: receipt.data.result.trackingId };
});
```

## Composables in pages and components

The module registers global auto-imports for:

* `useSendMail`
* `useMailbox`
* `useDomains`
* `useSpamCheck`
* `useWazobiaMail`

```vue theme={null}
<script setup lang="ts">
const { send, isLoading, error } = useSendMail();
</script>

<template>
  <button :disabled="isLoading" @click="send({ to: 'customer@example.com', subject: 'Hi', html: '<p>Hello</p>' })">
    Send
  </button>
</template>
```

For browser-side composables, route mutations through your own Nitro endpoints if you do not want a public key in the client bundle. The module's own `serverWazobiaClient` is the recommended path for sending.

## Environment variables

```env theme={null}
WAZOBIA_API_KEY=wzbm_live_...
WAZOBIA_BASE_URL=https://app.wazobiamail.com/api/v1
```

`WAZOBIAMAIL_API_KEY` is also accepted by the underlying SDK.

## Error handling

Wrap Nitro handlers with typed errors or return a safe server error:

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

try {
  await client.messages.send(message);
} catch (error) {
  if (error instanceof WazobiaRateLimitError) {
    throw createError({ statusCode: 429, statusMessage: 'Try again shortly' });
  }
  throw createError({ statusCode: 502, statusMessage: 'Email service unavailable' });
}
```

## Links

* [npm](https://www.npmjs.com/package/wazobiamail-nuxt)
* [GitHub](https://github.com/WazobiaMail/wazobiamail-nuxt)
* [Full README](https://github.com/WazobiaMail/wazobiamail-nuxt#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.