@artamail/nuxt

ArtaMail SDK module for Nuxt 3 applications. Send transactional and marketing emails with ease.

Installation

pnpm add @artamail/nuxt
# or
npm install @artamail/nuxt

Setup

Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@artamail/nuxt'],

  artamail: {
    apiKey: process.env.ARTAMAIL_API_KEY
  }
});

Or use environment variables:

NUXT_ARTAMAIL_API_KEY=am_live_sk_xxx

Usage

In Server API Routes

// server/api/send-email.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event);

  const result = await sendEmail({
    to: body.email,
    template: 'welcome',
    data: { name: body.name }
  });

  return result;
});

Using the Client Directly

// server/api/templates.get.ts
export default defineEventHandler(async () => {
  const artamail = useArtaMail();
  return artamail.listTemplates();
});

Sending Batch Emails

// server/api/notify.post.ts
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 result;
});

Configuration

Module Options

export default defineNuxtConfig({
  modules: ['@artamail/nuxt'],

  artamail: {
    // API key (required)
    apiKey: 'am_live_sk_xxx',

    // Base URL (optional)
    baseUrl: 'https://mail.artamail.com',

    // Request timeout in ms (default: 30000)
    timeout: 30000,

    // Retry attempts (default: 3)
    retries: 3
  }
});

Environment Variables

All options can be set via environment variables:

NUXT_ARTAMAIL_API_KEY=am_live_sk_xxx
NUXT_ARTAMAIL_BASE_URL=https://mail.artamail.com
NUXT_ARTAMAIL_TIMEOUT=30000
NUXT_ARTAMAIL_RETRIES=3

Server Composables

useArtaMail()

Get the ArtaMail client instance:

const artamail = useArtaMail();

// Send email
await artamail.send({ to: '...', template: '...', data: {} });

// Get templates
const templates = await artamail.listTemplates();

// Manage contacts
await artamail.upsertContact({ email: '...', name: '...' });

sendEmail(options)

Send a single email:

const result = await sendEmail({
  to: '[email protected]',
  template: 'welcome',
  data: { name: 'John' },
  priority: 'high'
});

sendBatchEmails(options)

Send multiple emails:

const result = await sendBatchEmails({
  emails: [
    { to: '[email protected]', template: 'notification', data: { ... } },
    { to: '[email protected]', template: 'notification', data: { ... } },
  ]
});

Error Handling

import {
  ValidationError,
  AuthenticationError,
  RateLimitError
} from '@artamail/sdk';

export default defineEventHandler(async (event) => {
  try {
    return await sendEmail({ ... });
  } catch (error) {
    if (error instanceof ValidationError) {
      throw createError({ statusCode: 400, message: error.message });
    }
    if (error instanceof AuthenticationError) {
      throw createError({ statusCode: 401, message: 'Invalid API key' });
    }
    if (error instanceof RateLimitError) {
      throw createError({ statusCode: 429, message: 'Rate limited' });
    }
    throw error;
  }
});

TypeScript

Full TypeScript support:

import type {
  SendEmailOptions,
  SendEmailResult,
  Template,
  Contact
} from '@artamail/sdk';

License

MIT