@artamail/nextjs

Next.js SDK

Official ArtaMail integration for Next.js 13+ applications with App Router support.

Installation

Terminal
pnpm add @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.com

Server Components

app/templates/page.tsx
1import { getArtaMail } from '@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 '@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 '@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}

Available Functions

getArtaMail()

Get a singleton ArtaMail client instance. Cached for efficiency.

typescript
const artamail = getArtaMail();
// With custom config
const artamail = getArtaMail({
  apiKey: 'am_live_sk_different_key',
  timeout: 60000
});

sendEmail()

Convenience function to send a single email.

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

sendBatchEmails()

Send multiple emails in a single batch (up to 1000).

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

listSenderAddresses()

Get available sender addresses for your organization.

typescript
const addresses = await listSenderAddresses();
const defaultAddress = addresses.find(a => a.isDefault);

Best Practices

Server-Side Only
The @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