@artatol/artamail-nextjs

Next.js SDK

Server-side integration for Next.js 13+ with App Router. A thin wrapper around @artatol/artamail-sdk — env config, singleton client, and email shortcuts.

Full SDK via getArtaMail()
Top-level exports like sendEmail() are convenience helpers. For contacts, subscriptions, double opt-in, templates, and everything else, use getArtaMail() — it returns the complete ArtaMail client from @artatol/artamail-sdk.

Installation

Terminal
pnpm add @artatol/artamail-nextjs

Configuration

Add your API key to environment variables:

.env.local
ARTAMAIL_API_KEY=am_live_sk_your_key_here
# Optional: custom API URL
ARTAMAIL_BASE_URL=https://artamail.artatol.net

Identity variables (auto-injected)

At send time ArtaMail fills brand, legal_entity, legal_address, and legal_detailsfrom Settings → Brand & compliance. Configure them in the dashboard; pass in data only to override. The full client is available via getArtaMail().

Legacy: company
The company field and {{company}} template variable are legacy aliases for brand. They still work today but may be removed in a future release.
Multiple products
Use a separate ArtaMail account (API key) per brand. See Multiple Products.

Server Components

app/templates/page.tsx
1import { getArtaMail } from '@artatol/artamail-nextjs/server';
2
3export default async function TemplatesPage() {
4  const artamail = getArtaMail();
5  const templates = await artamail.listTemplates();
6
7  return (
8    <ul>
9      {templates.map(t => (
10        <li key={t.id}>{t.name}</li>
11      ))}
12    </ul>
13  );
14}

Server Actions

app/actions.ts
1'use server'
2
3import { sendEmail } from '@artatol/artamail-nextjs/server';
4
5export async function sendWelcomeEmail(email: string, name: string) {
6  const result = await sendEmail({
7    to: email,
8    template: 'welcome',
9    data: { name }
10  });
11
12  return { success: true, emailId: result.id };
13}

Use the action in a Client Component:

app/signup/page.tsx
'use client'
import { sendWelcomeEmail } from '../actions';
export default function SignupPage() {
  async function handleSubmit(formData: FormData) {
    const email = formData.get('email') as string;
    const name = formData.get('name') as string;
    const result = await sendWelcomeEmail(email, name);
  }
  return (
    <form action={handleSubmit}>
      <input name="name" placeholder="Name" />
      <input name="email" placeholder="Email" />
      <button type="submit">Sign Up</button>
    </form>
  );
}

API Routes

app/api/send-email/route.ts
1import { sendEmail } from '@artatol/artamail-nextjs/server';
2import { NextResponse } from 'next/server';
3
4export async function POST(request: Request) {
5  const { to, template, data } = await request.json();
6
7  const result = await sendEmail({
8    to,
9    template,
10    data
11  });
12
13  return NextResponse.json({
14    success: true,
15    id: result.id,
16    testMode: result.testMode
17  });
18}

Signup with double opt-in

Use getArtaMail() for contacts and subscription consent — not the sendEmail() shortcut alone.

app/actions.ts
1'use server'
2
3import { getArtaMail } from '@artatol/artamail-nextjs/server';
4
5export async function subscribeNewsletter(email: string, name: string) {
6  const artamail = getArtaMail();
7
8  const contact = await artamail.optInContact({
9    email,
10    name,
11    optInSubtypeSlugs: ['weekly-digest'],
12    sendConfirmEmail: true,
13  });
14
15  return {
16    success: true,
17    pendingConfirmation: contact.pendingConfirmation,
18  };
19}
Subscriptions & consent guide

API surface

Package exports (shortcuts)

Import from @artatol/artamail-nextjs/server:

getArtaMail() / createArtaMail()

Return the full ArtaMail client. Prefer getArtaMail() (singleton) for most server code.

typescript
const artamail = getArtaMail({
  apiKey: 'am_live_sk_xxx', // optional — defaults to ARTAMAIL_API_KEY
  timeout: 60000,
});

sendEmail(), sendBatchEmails(), listSenderAddresses()

Shorthand for common email operations — equivalent to calling the same method on getArtaMail().

typescript
await sendEmail({
  to: '[email protected]',
  template: 'welcome',
  data: { name: 'John' },
  subtypeSlug: 'product-updates', // operational subtype — enforces consent
});

Full client (via getArtaMail())

All methods from @artatol/artamail-sdk are available on the client instance:

typescript
const artamail = getArtaMail();
// Emails
await artamail.send({ ... });
await artamail.sendBatch({ ... });
await artamail.getEmail('email-id');
// Contacts & consent
await artamail.upsertContact({ email, optInSubtypeSlugs: ['weekly-digest'] });
await artamail.optInContact({ email, optInSubtypeSlugs: [...], sendConfirmEmail: true });
await artamail.sendConsentConfirmEmail({ to, confirmUrl, name });
await artamail.getContact('[email protected]');
await artamail.updateContact('[email protected]', { subscribed: false });
// Permanent delete — PII, subscriptions, and list memberships removed
await artamail.deleteContact('[email protected]');
// Subscription types
await artamail.listSubscriptionTypes();
await artamail.getSubscriptionType('newsletter');
await artamail.getContactSubscriptionPreferences('[email protected]');
// Templates & senders
await artamail.listTemplates();
await artamail.getTemplate('welcome');
await artamail.listSenderAddresses();

deleteContact permanently erases the contact and consent data (same as DELETE /api/v1/contacts/:email). Cannot be undone.

TypeScript

Types are re-exported from @artatol/artamail-nextjs/server:

typescript
import type {
  SendEmailOptions,
  Contact,
  OptInContactOptions,
  SubscriptionType,
  ContactSubscriptionPreference,
} from '@artatol/artamail-nextjs/server';

Best Practices

Server-Side Only
The @artatol/artamail-nextjs/server module should only be imported in server-side code. Never import it in Client Components.
  • Use Server Actions for form submissions to keep API keys secure
  • Use the singleton (getArtaMail()) for most cases
  • Handle errors gracefully and show user-friendly messages
  • Use test keys during development to avoid sending real emails