@artamail/nextjs

ArtaMail SDK integration for Next.js applications. Provides server-side helpers for sending transactional emails.

Installation

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

Setup

Add your API key to .env.local:

ARTAMAIL_API_KEY=am_live_sk_xxx

Usage

In Server Components

import { getArtaMail } from '@artamail/nextjs/server';

export default async function EmailsPage() {
  const artamail = getArtaMail();
  const templates = await artamail.listTemplates();

  return (
    <ul>
      {templates.map(t => (
        <li key={t.id}>{t.name}</li>
      ))}
    </ul>
  );
}

In Server Actions

'use server'

import { sendEmail } from '@artamail/nextjs/server';

export async function sendWelcomeEmail(formData: FormData) {
  const email = formData.get('email') as string;
  const name = formData.get('name') as string;

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

  return { success: true, emailId: result.id };
}

In API Routes

// app/api/send-email/route.ts
import { getArtaMail } from '@artamail/nextjs/server';
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const { to, template, data } = await request.json();

  const artamail = getArtaMail();
  const result = await artamail.send({ to, template, data });

  return NextResponse.json(result);
}

API Reference

getArtaMail(config?)

Get or create a singleton ArtaMail client instance.

import { getArtaMail } from '@artamail/nextjs/server';

const artamail = getArtaMail();
// or with custom config
const artamail = getArtaMail({
  apiKey: 'am_live_sk_xxx', // Optional, defaults to ARTAMAIL_API_KEY
  timeout: 60000,
});

createArtaMail(config?)

Create a new (non-singleton) client instance.

import { createArtaMail } from '@artamail/nextjs/server';

const liveClient = createArtaMail({ apiKey: 'am_live_sk_xxx' });
const testClient = createArtaMail({ apiKey: 'am_test_sk_xxx' });

sendEmail(options)

Send an email directly (convenience function).

import { sendEmail } from '@artamail/nextjs/server';

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

sendBatchEmails(options)

Send multiple emails in a batch.

import { sendBatchEmails } from '@artamail/nextjs/server';

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

Error Handling

import {
  sendEmail,
  ValidationError,
  AuthenticationError,
  RateLimitError
} from '@artamail/nextjs/server';

try {
  await sendEmail({ ... });
} catch (error) {
  if (error instanceof ValidationError) {
    // Invalid input
  } else if (error instanceof AuthenticationError) {
    // Invalid API key
  } else if (error instanceof RateLimitError) {
    // Rate limited
  }
}

TypeScript

Full TypeScript support with exported types:

import type {
  SendEmailOptions,
  SendEmailResult,
  Template
} from '@artamail/nextjs/server';

License

MIT