techxnix-mail/README.md

Techxnix Mail Library for NestJS applications - A powerful and easy-to-use mail module using SendGrid

# Techxnix Mail

A powerful and easy-to-use NestJS mail module for sending emails using SendGrid.

## Features

- 📧 Send plain text and HTML emails
- 📝 Support for SendGrid templates
- 📎 File attachments support
- 🔄 Dynamic template data
- 🎨 Custom sender information
- 📝 Comprehensive logging
- 🌐 Global module configuration
- 🔒 Type-safe interfaces

## Installation

```bash
npm install techxnix-mail
```

## Quick Start

1. Import `TechxnixMailModule` in your `app.module.ts`:

```typescript
import { TechxnixMailModule } from 'techxnix-mail';

@Module({
  imports: [
    TechxnixMailModule.forRoot({
      sendGridApiKey: process.env.SENDGRID_API_KEY,
      defaultFromEmail: process.env.DEFAULT_FROM_EMAIL, // optional
      defaultFromName: process.env.DEFAULT_FROM_NAME,   // optional
    }),
  ],
})
export class AppModule {}
```

2. Inject and use `MailService` in your services:

```typescript
import { MailService } from 'techxnix-mail';

@Injectable()
export class YourService {
  constructor(private readonly mailService: MailService) {}

  // Send a simple email
  async sendEmail() {
    await this.mailService.send({
      to: 'user@example.com',
      subject: 'Welcome!',
      text: 'Welcome to our platform!',
      html: '<h1>Welcome to our platform!</h1>',
    });
  }

  // Send using a SendGrid template
  async sendTemplateEmail() {
    await this.mailService.sendTemplate(
      'user@example.com',
      'd-template-id',
      { name: 'John' },
      { subject: 'Welcome!' }
    );
  }
}
```

## Configuration

### Environment Variables

```env
SENDGRID_API_KEY=your_sendgrid_api_key
DEFAULT_FROM_EMAIL=noreply@yourdomain.com
DEFAULT_FROM_NAME=Your App Name
```

### Configuration Options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| sendGridApiKey | string | Yes | Your SendGrid API key |
| defaultFromEmail | string | No | Default sender email address |
| defaultFromName | string | No | Default sender name |

## API Reference

### MailService

#### send(options: IMailOptions): Promise<boolean>

Send an email with the following options:

```typescript
interface IMailOptions {
  to: string | string[];
  subject: string;
  text?: string;
  html?: string;
  from?: {
    email?: string;
    name?: string;
  };
  templateId?: string;
  dynamicTemplateData?: Record<string, any>;
  attachments?: Array<{
    content: string;
    filename: string;
    type?: string;
    disposition?: string;
    contentId?: string;
  }>;
}
```

#### sendTemplate(to: string | string[], templateId: string, dynamicTemplateData: Record<string, any>, options?: Partial<IMailOptions>): Promise<boolean>

Send an email using a SendGrid template.

## Logging

The module includes comprehensive logging:

- Initialization logs
- Pre-send attempt logs
- Success/failure status
- Detailed error information
- Template usage logs

Example log output:
```
[MailService] SendGrid API Key configured
[MailService] Attempting to send email to: user@example.com
[MailService] Email sent successfully to user@example.com. Status: 202
```

## Error Handling

The module provides detailed error information in logs:
- SendGrid API errors
- Configuration issues
- Template rendering errors
- Network problems

## Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

MIT

## Support

For support, email support@techxnix.com or create an issue in our GitHub repository.