@artamail/nuxt

Nuxt 3 Module

Native Nuxt 3 module with auto-imports and runtime configuration.

Installation

Terminal
pnpm add @artamail/nuxt

Configuration

Add the module to your nuxt.config.ts:

nuxt.config.ts
1export default defineNuxtConfig({
2 modules: ['@artamail/nuxt'],
3
4 artamail: {
5 // Will be read from NUXT_ARTAMAIL_API_KEY env var if not set
6 apiKey: process.env.NUXT_ARTAMAIL_API_KEY,
7
8 // Optional
9 baseUrl: 'https://artamail.artatol.com',
10 timeout: 30000,
11 retries: 3
12 }
13});
.env
NUXT_ARTAMAIL_API_KEY=am_live_sk_your_key_here

API Routes

The module provides server-side composables via the #artamail/server import alias.

server/api/send-email.post.ts
1import { sendEmail } from '#artamail/server';
2
3export default defineEventHandler(async (event) => {
4 const body = await readBody(event);
5
6 const result = await sendEmail({
7 to: body.email,
8 template: 'welcome',
9 data: { name: body.name }
10 });
11
12 return {
13 success: true,
14 id: result.id,
15 testMode: result.testMode
16 };
17});

Using the Client Instance

server/api/templates.get.ts
1import { useArtaMail } from '#artamail/server';
2
3export default defineEventHandler(async () => {
4 const artamail = useArtaMail();
5 const templates = await artamail.listTemplates();
6
7 return templates.map(t => ({
8 slug: t.slug,
9 name: t.name,
10 variables: t.variables
11 }));
12});

Batch Emails

server/api/notify-users.post.ts
import { sendBatchEmails } from '#artamail/server';
export default defineEventHandler(async (event) => {
const { users, message } = await readBody(event);
const result = await sendBatchEmails({
emails: users.map((user) => ({
to: user.email,
template: 'notification',
data: { name: user.name, message }
}))
});
return { queued: result.queued, failed: result.failed };
});

Available Exports

All exports from #artamail/server:

Composables

  • useArtaMail()— Get the cached ArtaMail client instance

Helper Functions

  • sendEmail(options)— Send a single email
  • sendBatchEmails(options)— Send multiple emails in batch
  • listSenderAddresses()— Get sender addresses

Error Handling

server/api/send.post.ts
import { sendEmail } from '#artamail/server';
import { ValidationError, RateLimitError } from '@artamail/sdk';
export default defineEventHandler(async (event) => {
const body = await readBody(event);
try {
const result = await sendEmail({
to: body.email,
template: body.template,
data: body.data
});
return { success: true, id: result.id };
} catch (error) {
if (error instanceof ValidationError) {
throw createError({ statusCode: 400, message: error.message });
}
if (error instanceof RateLimitError) {
throw createError({ statusCode: 429, message: 'Too many requests' });
}
throw createError({ statusCode: 500, message: 'Failed to send email' });
}
});
Server-Side Only
All ArtaMail composables and functions are server-side only. They will throw an error if used in client-side code. Always use them in the server/ directory.