@teliagen/plugin-mail

Email sending plugin for the Teliagen Framework.

Overview

@teliagen/plugin-mail provides email sending capabilities:

• Multiple Drivers – Console, SMTP, SendGrid, Resend
• Template Support – Handlebars templates for HTML emails
• Queue Support – Background email sending
• Attachments – File attachments support
• Event-Driven – Listen to send events

Installation

npm install @teliagen/plugin-mail
# or
pnpm add @teliagen/plugin-mail

For specific providers:

# nodemailer (for SMTP)
npm install nodemailer
npm install -D @types/nodemailer

# SendGrid
npm install @sendgrid/mail

# Resend
npm install resend

Quick Start

import { TeliagenApp } from '@teliagen/server';
import { MailPlugin } from '@teliagen/plugin-mail';

const app = new TeliagenApp();
await app.initialize();

const mailPlugin = MailPlugin({
  name: 'mail',
  default: 'smtp',
  from: {
    name: 'My App',
    email: '[email protected]'
  },
  drivers: {
    smtp: {
      driver: 'smtp',
      host: 'smtp.example.com',
      port: 587,
      secure: false,
      auth: {
        user: process.env.SMTP_USER!,
        pass: process.env.SMTP_PASS!
      }
    }
  }
});

await app.registerPlugins([mailPlugin]);
await app.start();

Configuration

interface MailPluginOptions {
  name: string;                  // Plugin instance name
  default: string;               // Default driver name
  from: {
    name: string;                // Default sender name
    email: string;               // Default sender email
  };
  drivers: Record<string, DriverConfig>;
  templatesPath?: string;        // Path to email templates
}

// Console Driver (Development)
interface ConsoleDriverConfig {
  driver: 'console';
}

// SMTP Driver
interface SmtpDriverConfig {
  driver: 'smtp';
  host: string;
  port: number;
  secure?: boolean;
  auth: {
    user: string;
    pass: string;
  };
}

// SendGrid Driver
interface SendGridDriverConfig {
  driver: 'sendgrid';
  apiKey: string;
}

// Resend Driver
interface ResendDriverConfig {
  driver: 'resend';
  apiKey: string;
}

Complete Example

const mailPlugin = MailPlugin({
  name: 'mail',
  default: process.env.NODE_ENV === 'production' ? 'sendgrid' : 'console',
  from: {
    name: 'My App',
    email: '[email protected]'
  },
  templatesPath: './src/templates/emails',
  drivers: {
    // Console (development - logs to stdout)
    console: {
      driver: 'console'
    },
    
    // SMTP
    smtp: {
      driver: 'smtp',
      host: process.env.SMTP_HOST!,
      port: parseInt(process.env.SMTP_PORT || '587'),
      secure: process.env.SMTP_SECURE === 'true',
      auth: {
        user: process.env.SMTP_USER!,
        pass: process.env.SMTP_PASS!
      }
    },
    
    // SendGrid
    sendgrid: {
      driver: 'sendgrid',
      apiKey: process.env.SENDGRID_API_KEY!
    },
    
    // Resend
    resend: {
      driver: 'resend',
      apiKey: process.env.RESEND_API_KEY!
    }
  }
});

MailService API

const mail = mailPlugin.Service;

// Simple email
await mail.send({
  to: '[email protected]',
  subject: 'Welcome to My App',
  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>'
});

// With text fallback
await mail.send({
  to: '[email protected]',
  subject: 'Welcome',
  html: '<h1>Welcome!</h1>',
  text: 'Welcome!'
});

// Multiple recipients
await mail.send({
  to: ['[email protected]', '[email protected]'],
  cc: '[email protected]',
  bcc: '[email protected]',
  subject: 'Team Update',
  html: '<p>Team update content...</p>'
});

// Custom from address
await mail.send({
  from: { name: 'Support', email: '[email protected]' },
  to: '[email protected]',
  subject: 'Support Response',
  html: '<p>Your ticket has been resolved.</p>'
});

// With attachments
await mail.send({
  to: '[email protected]',
  subject: 'Invoice',
  html: '<p>Please find your invoice attached.</p>',
  attachments: [
    { filename: 'invoice.pdf', content: pdfBuffer },
    { filename: 'logo.png', path: './assets/logo.png' }
  ]
});

// Use specific driver
await mail.driver('sendgrid').send({
  to: '[email protected]',
  subject: 'Important',
  html: '<p>Sent via SendGrid</p>'
});

Templates

Create Handlebars templates for reusable emails:

src/templates/emails/
├── welcome.hbs
├── password-reset.hbs
├── invoice.hbs
└── partials/
    ├── header.hbs
    └── footer.hbs

Template Example

{{!-- welcome.hbs --}}
<!DOCTYPE html>
<html>
<head>
  <title>Welcome to {{appName}}</title>
</head>
<body>
  {{> header}}
  
  <h1>Welcome, {{user.name}}!</h1>
  <p>Thanks for joining {{appName}}.</p>
  
  <a href="{{verifyUrl}}">Verify your email</a>
  
  {{> footer}}
</body>
</html>

Using Templates

const mail = mailPlugin.Service;

await mail.sendTemplate({
  to: user.email,
  subject: 'Welcome to My App',
  template: 'welcome',
  data: {
    appName: 'My App',
    user: { name: user.name },
    verifyUrl: `https://myapp.com/verify?token=${token}`
  }
});

// Password reset
await mail.sendTemplate({
  to: user.email,
  subject: 'Reset Your Password',
  template: 'password-reset',
  data: {
    user: { name: user.name },
    resetUrl: `https://myapp.com/reset?token=${resetToken}`,
    expiresIn: '1 hour'
  }
});

Common Patterns

User Registration

EventBus.on('auth:registered', async ({ user }) => {
  await mail.sendTemplate({
    to: user.email,
    subject: 'Welcome to My App',
    template: 'welcome',
    data: { user }
  });
});

Password Reset

EventBus.on('auth:passwordResetRequested', async ({ user, token }) => {
  await mail.sendTemplate({
    to: user.email,
    subject: 'Password Reset Request',
    template: 'password-reset',
    data: {
      user,
      resetUrl: `${process.env.APP_URL}/reset-password?token=${token}`
    }
  });
});

Tenant Invitation

EventBus.on('tenant:invitationSent', async ({ invitation, tenant }) => {
  await mail.sendTemplate({
    to: invitation.email,
    subject: `You've been invited to join ${tenant.name}`,
    template: 'tenant-invitation',
    data: {
      tenant,
      acceptUrl: `${process.env.APP_URL}/accept-invite?token=${invitation.token}`
    }
  });
});

Using in Actions

import { Action, ActionProvider, Input } from '@teliagen/commons';

@ActionProvider('notifications', 'NotificationActions')
class NotificationActions {
  @Action('sendContactForm')
  async sendContactForm(@Input() input: ContactFormInput) {
    const mail = mailPlugin.Service;
    
    await mail.send({
      to: '[email protected]',
      subject: `Contact Form: ${input.subject}`,
      html: `
        <p><strong>From:</strong> ${input.name} (${input.email})</p>
        <p><strong>Message:</strong></p>
        <p>${input.message}</p>
      `,
      replyTo: input.email
    });
    
    return { success: true };
  }
}

Events

import { EventBus } from '@teliagen/commons';

EventBus.on('mail:sent', async ({ to, subject, driver }) => {
  console.log(`Email sent to ${to}: ${subject} (via ${driver})`);
});

EventBus.on('mail:failed', async ({ to, subject, error }) => {
  console.error(`Failed to send email to ${to}: ${error.message}`);
});

Testing

Use console driver in tests:

// test.config.ts
const mailPlugin = MailPlugin({
  name: 'mail',
  default: 'console',
  from: { name: 'Test', email: '[email protected]' },
  drivers: {
    console: { driver: 'console' }
  }
});

// Emails will be logged to console instead of sent

Requirements

• Node.js >= 18.0.0
• @teliagen/server >= 0.1.0

Related Packages

• @teliagen/plugin-auth – Authentication (password reset emails)
• @teliagen/plugin-tenant – Multi-tenancy (invitation emails)

Documentation

For full documentation, visit docs.teliagen.org.

License

MIT © Teliagen Contributors