@artamail/sdk

Official ArtaMail SDK for Node.js and browsers. Send transactional and marketing emails with ease.

Installation

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

Quick Start

import { ArtaMail } from '@artamail/sdk';

const artamail = new ArtaMail({
  apiKey: 'am_live_sk_xxx' // Get your API key from the dashboard
});

// Send a transactional email
const result = await artamail.send({
  to: '[email protected]',
  template: 'welcome',
  data: {
    name: 'John',
    verifyUrl: 'https://example.com/verify?token=xxx'
  }
});

console.log('Email queued:', result.id);

API Reference

Configuration

const artamail = new ArtaMail({
  apiKey: 'am_live_sk_xxx',  // Required
  baseUrl: 'https://mail.artamail.com', // Optional
  timeout: 30000,  // Request timeout in ms (default: 30000)
  retries: 3,      // Retry attempts (default: 3)
});

Sending Emails

Single Email

const result = await artamail.send({
  to: '[email protected]',
  template: 'welcome',
  data: { name: 'John' },

  // Optional
  from: '[email protected]',
  fromName: 'Your Company',
  replyTo: '[email protected]',
  priority: 'high', // 'high' | 'normal' | 'low'
  addToContacts: true,
  metadata: { userId: '123' }
});

Batch Emails

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

console.log(`Queued: ${result.queued}, Failed: ${result.failed}`);

Get Email Status

const email = await artamail.getEmail('email-id');
console.log(email.status); // 'queued' | 'sent' | 'delivered' | 'bounced' | ...

Contacts

// Create or update a contact
const contact = await artamail.upsertContact({
  email: '[email protected]',
  name: 'John Doe',
  data: { company: 'Acme Inc', role: 'Developer' },
  lists: ['newsletter', 'product-updates']
});

// Get a contact
const contact = await artamail.getContact('[email protected]');

// Update a contact
await artamail.updateContact('[email protected]', {
  name: 'Jane Doe',
  subscribed: false
});

// Delete a contact
await artamail.deleteContact('[email protected]');

Templates

// List all templates
const templates = await artamail.listTemplates();

// Get template details
const template = await artamail.getTemplate('welcome');
console.log(template.variables); // ['name', 'verifyUrl']

Error Handling

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

try {
  await artamail.send({ ... });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof ArtaMailError) {
    console.error('API error:', error.code, error.message);
  }
}

TypeScript

This package is written in TypeScript and includes full type definitions.

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

Framework Integrations

• Next.js: Use @artamail/nextjs for server-side helpers
• Nuxt: Use @artamail/nuxt for Nuxt 3 plugin

License

MIT