📧 Mail Service Drivers

Mail service drivers provide a consistent interface for sending emails in NodeBlocks applications. They abstract email provider configurations and operations, allowing you to use different email services without changing your business logic.

---

🎯 Overview

Mail service drivers in NodeBlocks are factory functions that create configured email service instances. They provide:

• Consistent interface across different email providers
• Simple configuration with API keys and settings
• Flexible implementation for custom email providers

---

📋 Available Mail Service Drivers

SendGrid Driver

The SendGrid driver creates a configured SendGrid mail service for sending emails through the SendGrid API.

getSendGridClient

Creates a SendGrid mail service client with API key and optional base URL configuration.

Parameters:

• apiKey: string - SendGrid API key for authentication
• baseUrl?: string - Optional base URL for SendGrid API (useful for testing/staging)

Returns: MailService - Configured mail service with sendMail method

Usage:

import { getSendGridClient } from '@nodeblocks/backend-sdk/drivers';

const mailService = getSendGridClient(process.env.SENDGRID_API_KEY);

Example with Custom Base URL:

import { getSendGridClient } from '@nodeblocks/backend-sdk/drivers';

const mailService = getSendGridClient(
  process.env.SENDGRID_API_KEY,
  'https://api.sendgrid.com/v3'
);

Example with Options:

import { getSendGridClient } from '@nodeblocks/backend-sdk/drivers';

const mailService = getSendGridClient(process.env.SENDGRID_API_KEY);

// Send with logging enabled
const success = await mailService.sendMail({
  to: 'user@example.com',
  from: 'noreply@company.com',
  subject: 'Welcome!',
  text: 'Welcome to our platform'
}, {
  logger: myLogger,
  sandboxMode: process.env.NODE_ENV === 'development'
});

setBaseUrl

Sets the base URL for SendGrid API requests to enable custom endpoints or testing.

Parameters:

• baseUrl: string - Base URL for SendGrid API requests (e.g., 'https://api.sendgrid.com/v3')

Usage:

import { setBaseUrl } from '@nodeblocks/backend-sdk/drivers';

// Set production SendGrid API URL
setBaseUrl('https://api.sendgrid.com/v3');

// Set staging/testing URL
setBaseUrl('https://api-staging.sendgrid.com/v3');

---

🔧 Using Mail Service Drivers

Direct Usage

Use mail service drivers directly for sending emails:

import { getSendGridClient } from '@nodeblocks/backend-sdk/drivers';

const mailService = getSendGridClient(process.env.SENDGRID_API_KEY);

// Send email using the service
const success = await mailService.sendMail({
  to: 'identity@example.com',
  from: 'noreply@company.com',
  subject: 'Welcome!',
  text: 'Welcome to our platform'
});

---

📧 Mail Interfaces

Mail Data Interface

The MailData interface defines the structure for email messages. It requires basic email fields and content, with a simple but strict structure:

// Required fields for all emails
interface RequiredMailData {
  from: string;    // Sender email address
  subject: string; // Email subject line
  to: string;      // Recipient email address
}

// Complete email data - requires content (HTML or text)
type MailData = RequiredMailData & ({ html: string } | { text: string });

Interface Rules:

• Always required: from, subject, and to fields
• Content choice: Include either html OR text content (not both)
• Single recipient: Only one recipient per email
• No attachments: File attachments are not supported

Usage Examples:

// ✅ Valid: HTML email
const htmlEmail: MailData = {
  to: 'identity@example.com',
  from: 'noreply@company.com',
  subject: 'Welcome!',
  html: '<h1>Welcome!</h1><p>Thank you for joining.</p>'
};

// ✅ Valid: Text email
const textEmail: MailData = {
  to: 'identity@example.com',
  from: 'noreply@company.com',
  subject: 'Password Reset',
  text: 'Your reset token: ABC123'
};

Mail Service Interface

The MailService interface defines the contract for all mail service drivers:

interface MailService {
  sendMail(mailData: MailData, opts?: MailOptions): Promise<boolean>;
}

Parameters:

• mailData: MailData - Email data including sender, recipient, subject, and content
• opts?: MailOptions - Optional configuration (sandbox mode, logger)

Returns: Promise<boolean> - true if email sent successfully (status code 202), false otherwise

MailOptions:

interface MailOptions {
  logger?: Logger;      // Optional logger for debugging
  sandboxMode?: boolean; // Enable sandbox mode for testing
}