@scwar/nestjs-mailjet-sdk

A comprehensive NestJS module for integrating with Mailjet API v3.1. This package provides a complete wrapper around Mailjet's email sending capabilities with robust error handling, retries, and TypeScript support.

Features

• 🚀 Complete API Coverage: Mailjet API v3.1 endpoints implemented
• 🔄 Automatic Retries: Built-in retry mechanism with exponential backoff
• 🛡️ Robust Error Handling: Comprehensive error handling with detailed error messages
• 📝 TypeScript Support: Full type definitions for all API requests and responses
• 🧪 Comprehensive Testing: Extensive test coverage for all endpoints
• ⚡ Performance: Uses native fetch API for optimal performance
• 🔧 Configurable: Easy configuration through NestJS module options

Installation

npm install @scwar/nestjs-mailjet-sdk

Quick Start

1. Import the module

import { MailjetModule } from '@scwar/nestjs-mailjet-sdk';

@Module({
  imports: [
    MailjetModule.forRoot({
      apiKey: 'your-mailjet-api-key',
      apiSecret: 'your-mailjet-api-secret',
      baseUrl: 'https://api.mailjet.com/v3.1',
      timeout: 30000,
      retries: 3,
    }),
  ],
})
export class AppModule {}

2. Inject and use the service

import { MailjetService } from '@scwar/nestjs-mailjet-sdk';

@Injectable()
export class EmailService {
  constructor(private readonly mailjetService: MailjetService) {}

  async sendWelcomeEmail(userEmail: string, userName: string) {
    return this.mailjetService.send.sendEmail({
      From: {
        Email: '[email protected]',
        Name: 'Example App',
      },
      To: [
        {
          Email: userEmail,
          Name: userName,
        },
      ],
      Subject: 'Welcome to Example App',
      HTMLPart: `
        <h1>Welcome ${userName}!</h1>
        <p>Thank you for joining Example App.</p>
      `,
      TextPart: `Welcome ${userName}! Thank you for joining Example App.`,
    });
  }
}

Configuration Options

interface MailjetModuleOptions {
  apiKey: string;
  apiSecret: string;
  baseUrl?: string;        // Default: 'https://api.mailjet.com/v3.1'
  timeout?: number;        // Default: 30000
  retries?: number;        // Default: 3
  retryDelay?: number;     // Default: 1000
  maxRetryDelay?: number;  // Default: 10000
}

Async Configuration

import { ConfigModule, ConfigService } from '@nestjs/config';
import { MailjetModule } from '@scwar/nestjs-mailjet-sdk';

@Module({
  imports: [
    ConfigModule.forRoot(),
    MailjetModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        apiKey: configService.get<string>('MAILJET_API_KEY'),
        apiSecret: configService.get<string>('MAILJET_API_SECRET'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Available Services

Send Service

Send transactional and bulk emails:

// Send a single email
await mailjetService.send.sendEmail({
  From: { Email: '[email protected]', Name: 'Sender' },
  To: [{ Email: '[email protected]', Name: 'Recipient' }],
  Subject: 'Hello',
  HTMLPart: '<h1>Hello World</h1>',
  TextPart: 'Hello World',
});

// Send using template
await mailjetService.send.sendTemplate(
  templateId,
  { Email: '[email protected]' },
  [{ Email: '[email protected]' }],
  { name: 'John' },
);

// Send bulk emails
await mailjetService.send.sendBulk([
  { From: {...}, To: [...], Subject: '...', HTMLPart: '...' },
  { From: {...}, To: [...], Subject: '...', HTMLPart: '...' },
]);

Contact Service

Manage contacts and contact lists:

// Create contact
await mailjetService.contact.create({
  Email: '[email protected]',
  Name: 'John Doe',
  IsExcludedFromCampaigns: false,
});

// Get contact
await mailjetService.contact.getByEmail('[email protected]');

// List contacts
await mailjetService.contact.list({
  Limit: 10,
  Offset: 0,
});

// Update contact
await mailjetService.contact.updateByEmail('[email protected]', {
  Name: 'Jane Doe',
});

// Manage contact lists
await mailjetService.contact.manageContactList(contactId, {
  ContactsLists: [
    { ListID: 123, Action: 'addnoforce' },
  ],
});

Template Service

Manage email templates:

// Create template
await mailjetService.template.create({
  Name: 'Welcome Template',
  Author: 'John Doe',
});

// Get template
await mailjetService.template.get(templateId);

// List templates
await mailjetService.template.list({
  Limit: 10,
  Offset: 0,
});

// Update template
await mailjetService.template.update(templateId, {
  Name: 'Updated Template Name',
});

// Get template content
await mailjetService.template.getContent(templateId);

// Set template content
await mailjetService.template.setContent(templateId, {
  'Html-part': '<h1>Hello</h1>',
  'Text-part': 'Hello',
});

Statistics Service

Get email and campaign statistics:

// Get email statistics
await mailjetService.statistics.getEmailStatistics({
  FromTS: '2024-01-01T00:00:00Z',
  ToTS: '2024-01-31T23:59:59Z',
});

// Get campaign statistics
await mailjetService.statistics.getCampaignStatistics({
  CampaignID: 123,
});

// Get message statistics
await mailjetService.statistics.getMessageStatistics(messageId);

// Get contact statistics
await mailjetService.statistics.getContactStatistics(contactId);

Error Handling

The package provides comprehensive error handling with detailed error messages:

import { MailjetError } from '@scwar/nestjs-mailjet-sdk';

try {
  const result = await this.mailjetService.send.sendEmail(data);
} catch (error) {
  if (error instanceof MailjetError) {
    console.log('Mailjet Error:', error.message);
    console.log('Error Code:', error.code);
    console.log('HTTP Status:', error.status);
    console.log('Error Data:', error.data);
  }
}

Retry Mechanism

Automatic retries with exponential backoff for failed requests:

// Configure retries in module options
MailjetModule.forRoot({
  apiKey: 'your-key',
  apiSecret: 'your-secret',
  retries: 3,           // Number of retry attempts
  retryDelay: 1000,     // Initial delay in ms
  maxRetryDelay: 10000, // Maximum delay in ms
})

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:cov

Version Management & Releases

This package includes an automated version bumping system that follows semantic versioning and conventional commits.

Automatic Version Bumping

The system automatically determines the appropriate version bump based on your commits:

# Automatically determine and bump version
npm run version:auto

# Manual version bumps
npm run version:patch  # 1.0.0 → 1.0.1
npm run version:minor  # 1.0.0 → 1.1.0
npm run version:major  # 1.0.0 → 2.0.0

Conventional Commits

All commits must follow the Conventional Commits specification:

# Feature commits (minor version bump)
git commit -m "feat: add new email template support"

# Bug fix commits (patch version bump)
git commit -m "fix: resolve authentication issue"

# Breaking change commits (major version bump)
git commit -m "feat!: breaking change in API"

# Documentation commits (no version bump)
git commit -m "docs: update README with examples"

Release Process

Automated Release (Recommended)

# Complete release process with automatic version bump
npm run release:auto

# Manual release with specific version bump
npm run release:patch
npm run release:minor
npm run release:major

See VERSION_BUMPING_GUIDE.md for detailed information.

GitHub Actions

The package includes GitHub Actions workflows for:

• CI: Automated testing, linting, and quality checks
• Release: Automated version bumping, changelog updates, and npm publishing

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using conventional commit format
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Important: All commits must follow the conventional commit format to ensure proper version bumping.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please open an issue on GitHub or contact the maintainers.

Changelog

See CHANGELOG.md for a list of changes and version history.

References

• Mailjet API Documentation
• NestJS Documentation
• Conventional Commits