Guide

Sending Emails

A complete guide to sending transactional emails with ArtaMail.

Basic Email Sending

The simplest way to send an email is using a template with the recipient's email:

typescript
import { sendEmail } from '@artamail/nextjs/server';
await sendEmail({
  to: '[email protected]',
  template: 'welcome',
  data: { name: 'John' }
});

Template Variables

Check what variables a template needs and provide them:

typescript
// Check template requirements
const template = await artamail.getTemplate('welcome');
console.log('Variables:', template.variables);
// → ['name', 'verifyUrl', 'company']
// Send with all required variables
await artamail.send({
  to: '[email protected]',
  template: 'welcome',
  data: {
    name: 'John Doe',
    verifyUrl: 'https://example.com/verify/abc123',
    company: 'Acme Inc'
  }
});

Custom Sender

By default, emails are sent from your organization's default sender address. You can specify a different verified sender:

typescript
await sendEmail({
  to: '[email protected]',
  template: 'invoice',
  data: { ... },
  from: '[email protected]',
  fromName: 'Billing Team'
});

Email Priority

Control email queue processing order:

typescript
// High priority (processed first)
await sendEmail({
  to: '[email protected]',
  template: 'password-reset',
  priority: 'high'
});
// Low priority (processed when queue is less busy)
await sendEmail({
  to: '[email protected]',
  template: 'weekly-digest',
  priority: 'low'
});

Batch Sending

Send multiple emails efficiently in a single request (max 1000):

typescript
const users = [
  { email: '[email protected]', name: 'User 1' },
  { email: '[email protected]', name: 'User 2' },
  { email: '[email protected]', name: 'User 3' },
];
const result = await artamail.sendBatch({
  emails: users.map(user => ({
    to: user.email,
    template: 'notification',
    data: { name: user.name, message: 'Hello!' }
  }))
});
console.log(`Queued: ${result.queued}, Failed: ${result.failed}`);

Checking Email Status

Track email delivery status:

typescript
const result = await sendEmail({
  to: '[email protected]',
  template: 'welcome'
});
// Check status later
const email = await artamail.getEmail(result.id);
console.log('Status:', email.status);  // queued → sent → delivered
if (email.openedAt) {
  console.log('Opened at:', email.openedAt);
}

Test Mode

Use test API keys during development to avoid sending real emails:

typescript
// With test key (am_test_sk_xxx)
const result = await sendEmail({
  to: '[email protected]',
  template: 'welcome'
});
console.log(result.testMode);  // true
console.log(result.id);        // test_550e8400-... (prefixed)
// Email is not actually sent, but you get a valid response
Development tip
Always use test keys in development to avoid accidentally sending emails to real users.