@xcelsior/email

Email service for sending and managing emails in Xcelsior applications.

Installation

pnpm add @xcelsior/email

Features

Email Service

Send emails with multiple provider support:

import { EmailService } from '@xcelsior/email';

const email = new EmailService({
  provider: 'ses',
  from: '[email protected]',
  logger: console,
});

// Send simple email
await email.send({
  to: '[email protected]',
  subject: 'Welcome!',
  text: 'Welcome to our service',
});

// Send HTML email with attachments
await email.send({
  to: ['[email protected]', '[email protected]'],
  subject: 'Monthly Report',
  html: '<h1>Report</h1><p>Content...</p>',
  attachments: [{
    filename: 'report.pdf',
    content: Buffer.from('...'),
  }],
});

Email Logging

Track email sending history:

import { EmailLogger } from '@xcelsior/email';

const logger = new EmailLogger({
  storage: new DynamoDBStorage(),
});

// Log email
await logger.log({
  messageId: 'msg123',
  to: '[email protected]',
  subject: 'Welcome',
  status: 'sent',
});

// Get email history
const history = await logger.getHistory({
  recipient: '[email protected]',
  limit: 10,
});

Template Support

Use templates for consistent emails:

import { EmailTemplate } from '@xcelsior/email';

// Create template
const template = new EmailTemplate({
  subject: 'Welcome to {{serviceName}}',
  html: '<h1>Welcome {{name}}</h1>',
});

// Send templated email
await email.sendTemplate('welcome', {
  to: '[email protected]',
  data: {
    serviceName: 'Our Service',
    name: 'John',
  },
});

Configuration

Service Options

interface EmailOptions {
  provider: 'ses' | 'smtp' | 'test';
  from: string;
  logger?: Logger;
  defaults?: {
    replyTo?: string;
    cc?: string[];
    bcc?: string[];
  };
}

Provider Options

// SES Provider
const email = new EmailService({
  provider: 'ses',
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'YOUR_ACCESS_KEY',
    secretAccessKey: 'YOUR_SECRET_KEY',
  },
});

// SMTP Provider
const email = new EmailService({
  provider: 'smtp',
  host: 'smtp.example.com',
  port: 587,
  secure: true,
  auth: {
    user: 'username',
    pass: 'password',
  },
});

Types

interface EmailMessage {
  to: string | string[];
  subject: string;
  text?: string;
  html?: string;
  attachments?: Attachment[];
  cc?: string[];
  bcc?: string[];
  replyTo?: string;
}

interface Attachment {
  filename: string;
  content: Buffer | string;
  contentType?: string;
}

Error Handling

try {
  await email.send(message);
} catch (error) {
  if (error instanceof EmailError) {
    switch (error.code) {
      case 'InvalidRecipient':
        // Handle invalid recipient
        break;
      case 'DeliveryFailed':
        // Handle delivery failure
        break;
    }
  }
  throw error;
}

License

MIT