npm package: @pixelplex/mail-service
Description: Mail service
Author: dev@pixelplex.io
Latest version: 0.2.8

# Mail Service

Library for sending email messages through configured gateways.

## Supported gateways

- slack
- console
- smtp
- sendgrid
- resend

## Templates

The service uses Handlebars as the template engine.

Expected template files:

- `{name}.handlebars` for HTML body
- `{name}.subject.handlebars` for subject
- `{name}.plain.handlebars` for plain-text body

Example:

```handlebars
# welcome.subject.handlebars Welcome, {{name}}!
```

```handlebars
# welcome.handlebars
<html>
  <head></head>
  <body>
    <p>Welcome, {{name}}!</p>
  </body>
</html>
```

```handlebars
# welcome.plain.handlebars Welcome, {{name}}!
```

## Configuration

| Name            | Description                                              | Example                   |
| --------------- | -------------------------------------------------------- | ------------------------- |
| gateways        | Array of gateways to send email                          | `['resend']`              |
| customGateways  | Array of custom gateways classes                         | `[CustomGateway]`         |
| smtp.host       | Mail gateway host address                                | `smtp.gmail.com`          |
| smtp.port       | Mail gateway port number                                 | `586`                     |
| smtp.username   | Mail gateway username                                    | `username`                |
| smtp.password   | Mail gateway password                                    | `qh05780c2qcm034579`      |
| \*.sender       | Mail sender address                                      | `postmail@pixelplex.io`   |
| slack.url       | Hook URL in case you want to duplicate messages to Slack | `https://hooks.slack.com` |
| sendgrid.apiKey | Sendgrid API key                                         | `oiqur9823uiofhaoafoe`    |
| resend.apiKey   | Resend API key                                           | `re_xxxxxxxxx`            |

### Resend config

```typescript
export const mailConfig = {
  gateways: ['resend'],
  resend: {
    apiKey: process.env.RESEND_API_KEY,
    sender: process.env.MAIL_SENDER,
  },
};
```

## Usage

```bash
yarn add @pixelplex/mail-service
```

```typescript
import { Module } from '@nestjs/common';
import { MailModule } from '@pixelplex/mail-service';
import { AppService } from './app.service';

@Module({
  imports: [
    MailModule.forRoot({
      gateways: ['slack', 'smtp', 'console', 'resend'],
      slack: { url: 'hooks.slack.com' },
      smtp: {
        username: 'postmail@pixelplex.io',
        sender: 'postmail@pixelplex.io',
        host: 'smtp.ethereal.com',
        port: 678,
        password: 'password',
      },
      resend: {
        apiKey: RESEND_API_KEY,
        sender: MAIL_SENDER,
      },
    }),
  ],
  providers: [AppService],
})
export class AppModule {}
```

```typescript
import { Injectable } from '@nestjs/common';
import { MailSenderService } from '@pixelplex/mail-service';

@Injectable()
export class AppService {
  constructor(private readonly mailSenderService: MailSenderService) {}

  async sendWelcomeEmail() {
    await this.mailSenderService.sendEmail(
      'test@gmail.com',
      {
        htmlPath: htmlTemplatePath,
        plainPath: plainTextTemplatePath,
        subjectPath: subjectTemplatePath,
      },
      { year: 20 },
    );
  }
}
```

`{ year: 20 }` is the Handlebars context passed into the templates.

React templates are not supported at the moment. The package supports the same Handlebars-based flow as before, including for the new `resend` gateway.

## Custom gateways

To add a custom gateway, provide a class that implements `IGateway` in `customGateways`.

```typescript
import { Injectable } from '@nestjs/common';
import { Content, IGateway } from '@pixelplex/mail-service';

@Injectable()
class CustomGateway implements IGateway {
  async send(to: string, content: Content): Promise<void> {
    console.log('this is custom gateway');
  }
}

MailModule.forRoot({
  gateways: ['console'],
  customGateways: [CustomGateway],
});
```