@tresdoce-nestjs-toolkit/mailer

v2.0.12

Published

23 days ago

Tresdoce NestJS Toolkit - Módulo para envíos de mail

0High
0Medium
0Low

Este módulo está pensado para ser utilizado en NestJS Starter, o cualquier proyecto que utilice una configuración centralizada, siguiendo la misma arquitectura del starter.

Glosario

📝 Requerimientos básicos

NestJS Starter
Node.js v22.21.1 or higher (Download)
YARN ≥ 1.22.22 o NPM ≥ 11.6.4
NestJS v11.1.11 or higher (Documentación)

🛠️ Instalar dependencia

npm install -S @tresdoce-nestjs-toolkit/mailer

yarn add @tresdoce-nestjs-toolkit/mailer

📦 Dependencias internas

Este paquete no tiene dependencias internas del toolkit. Puede utilizarse de forma independiente.

⚙️ Configuración

Agregar los datos de conexión SMTP en configuration.ts utilizando el key mailer que contenga los datos desde las variables de entorno.

//./src/config/configuration.ts
import { Typings } from '@tresdoce-nestjs-toolkit/core';
import { registerAs } from '@nestjs/config';
import { join } from 'path';
import { HandlebarsAdapter } from '@tresdoce-nestjs-toolkit/mailer';

export default registerAs('config', (): Typings.AppConfig => {
  return {
    //...
    mailer: {
      transport: {
        host: process.env.EMAIL_HOST,
        port: parseInt(process.env.EMAIL_PORT, 10) || 587,
        secure: true,
        requireTLS: true,
        auth: {
          user: process.env.EMAIL_USER,
          pass: process.env.EMAIL_PASSWORD,
        },
      },
      defaults: {
        from: process.env.EMAIL_USER,
      },
      // Opcional: configuración de templates
      template: {
        dir: join(__dirname, './templates'),
        adapter: new HandlebarsAdapter(),
        options: {
          strict: true,
        },
      },
    },
    //...
  };
});

transport: Configuración del transporte SMTP. Puede ser un objeto de opciones, una cadena de conexión URL (smtps://[email protected]:[email protected]) o una instancia de transporte nodemailer.

Type: SMTPTransport.Options | string | Transport
Required: true (a menos que se use transports)

transport.host: Servidor SMTP.

Type: String

transport.port: Puerto SMTP.

Type: Number
Default: 587

transport.secure: Utilizar TLS.

Type: Boolean
Default: true

transport.requireTLS: Exige TLS aunque secure sea false.

Type: Boolean
Default: true

Nota: Las constantes defaultTransportOptions exportadas por el módulo tienen preconfigurado { secure: true, requireTLS: true }.

transport.auth.user: Usuario SMTP.

Type: String

transport.auth.pass: Contraseña SMTP.

Type: String

transports: Permite configurar múltiples transportadores con nombre para usar en entornos multi-tenant o multi-cuenta.

Type: { [name: string]: SMTPTransport | SMTPTransport.Options | string }
Required: false

defaults: Opciones por defecto aplicadas a todos los correos enviados.

Type: Object
Example: { from: '"App" <[email protected]>' }

template.dir: Directorio donde se encuentran los templates de email.

Type: String

template.adapter: Adaptador de template a usar (HandlebarsAdapter, EjsAdapter o PugAdapter).

Type: TemplateAdapter

template.options: Opciones adicionales pasadas al adaptador de template (ej. { strict: true } para Handlebars).

Type: Object

options.partials.dir: Directorio de partials de Handlebars (sólo aplica con HandlebarsAdapter).

Type: String

👨‍💻 Uso

Importación del módulo (configuración centralizada)

Importar el MailerModule en el archivo app.module.ts. El módulo obtiene la configuración automáticamente desde ConfigService (key config.mailer).

//./src/app.module.ts
import { MailerModule } from '@tresdoce-nestjs-toolkit/mailer';

@Module({
  //...
  imports: [
    //...
    MailerModule,
    //...
  ],
  //...
})
export class AppModule {}

Importación estática con `forRoot`

Cuando no se usa la configuración centralizada, se puede inicializar el módulo directamente con forRoot:

//./src/app.module.ts
import { MailerModule } from '@tresdoce-nestjs-toolkit/mailer';

@Module({
  imports: [
    MailerModule.forRoot({
      transport: 'smtps://[email protected]:[email protected]',
      defaults: {
        from: '"App" <[email protected]>',
      },
    }),
  ],
})
export class AppModule {}

Envío de email simple

Inyectar el MailerService para realizar el envío de mails.

//./src/app.service.ts
import { Injectable } from '@nestjs/common';
import { MailerService } from '@tresdoce-nestjs-toolkit/mailer';

@Injectable()
export class AppService {
  constructor(private readonly mailerService: MailerService) {}

  async sendMail() {
    try {
      return await this.mailerService.sendMail({
        to: 'destinatario <[email protected]>',
        from: 'remitente <[email protected]>',
        subject: 'Asunto del mail',
        text: 'Cuerpo en texto plano',
        html: '<b>Cuerpo en HTML</b>',
      });
    } catch (error) {
      throw new Error(error.message);
    }
  }
}

Templates de email

Se pueden usar tres adaptadores de template: Handlebars, EJS y Pug.

Handlebars

//./src/config/configuration.ts
import { join } from 'path';
import { HandlebarsAdapter } from '@tresdoce-nestjs-toolkit/mailer';

mailer: {
  transport: { /* ... */ },
  template: {
    dir: join(__dirname, './templates'),
    adapter: new HandlebarsAdapter(),
    options: {
      strict: true,
    },
  },
  // Soporte de partials: directorio con archivos *.hbs registrados automáticamente
  options: {
    partials: {
      dir: join(__dirname, './templates/partials'),
    },
  },
}

Template Handlebars (templates/welcome.hbs):

<p>Hola {{name}},</p>
<p>Bienvenido a NestJS Mailer.</p>

await this.mailerService.sendMail({
  to: email,
  subject: 'Bienvenido',
  template: './welcome',
  context: { name: 'Juan' },
});

EJS

//./src/config/configuration.ts
import { join } from 'path';
import { EjsAdapter } from '@tresdoce-nestjs-toolkit/mailer';

mailer: {
  transport: { /* ... */ },
  template: {
    dir: join(__dirname, './templates'),
    adapter: new EjsAdapter(),
  },
}

Template EJS (templates/welcome.ejs):

<p>Hola <%= name %>,</p>
<p>Bienvenido a NestJS Mailer.</p>

await this.mailerService.sendMail({
  to: email,
  subject: 'Bienvenido',
  template: './welcome',
  context: { name: 'Juan' },
});

Pug

//./src/config/configuration.ts
import { join } from 'path';
import { PugAdapter } from '@tresdoce-nestjs-toolkit/mailer';

mailer: {
  transport: { /* ... */ },
  template: {
    dir: join(__dirname, './templates'),
    adapter: new PugAdapter(),
  },
}

Template Pug (templates/welcome.pug):

p Hola #{name},
p Bienvenido a NestJS Mailer.

await this.mailerService.sendMail({
  to: email,
  subject: 'Bienvenido',
  template: './welcome',
  context: { name: 'Juan' },
});

CSS Inline

Todos los adaptadores tienen el inlining de CSS habilitado por defecto (inlineCssEnabled: true). Para deshabilitar o personalizar:

new HandlebarsAdapter(undefined, {
  inlineCssEnabled: false,
});

// O con opciones de @css-inline/css-inline:
new EjsAdapter({
  inlineCssEnabled: true,
  inlineCssOptions: {
    /* opciones de css-inline */
  },
});

Múltiples transportadores

Cuando se necesita enviar correos desde distintas cuentas, se puede configurar transports:

mailer: {
  transports: {
    primary: {
      host: process.env.EMAIL_HOST_PRIMARY,
      port: 587,
      auth: { user: process.env.EMAIL_USER_PRIMARY, pass: process.env.EMAIL_PASS_PRIMARY },
    },
    secondary: 'smtps://[email protected]:[email protected]',
  },
  defaults: { from: '"App" <[email protected]>' },
}

Para enrutar el envío a un transportador específico, se usa el campo transporterName:

await this.mailerService.sendMail({
  to: '[email protected]',
  subject: 'Asunto',
  text: 'Mensaje',
  transporterName: 'secondary', // nombre de la clave en transports
});

📖 API Reference

`MailerModule`

| Método | Descripción | | ----------------------------------------------- | --------------------------------------------------------------------------------------------- | | MailerModule (sin argumentos) | Carga la configuración desde ConfigService (key config.mailer). Decorado con @Global(). | | MailerModule.forRoot(options?: MailerOptions) | Inicialización estática con opciones directas. |

`MailerService`

| Método | Descripción | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | sendMail(options: ISendMailOptions): Promise<SentMessageInfo> | Envía un email. Si options.transporterName está definido, usa ese transportador; de lo contrario usa el transportador único. |

`ISendMailOptions`

| Campo | Tipo | ----------------- | to | cc | bcc | from | replyTo | inReplyTo | subject | text | html | sender | raw | textEncoding | references | encoding | date | headers | attachments | dkim | template | context | transporterName | Descripción | | ------------------------------------------ | --------------------------------------------------------------- | | EmailAddress | Destinatario(s) | | EmailAddress | Copia(s) | | EmailAddress | Copia(s) oculta(s) | | string \| Address | Remitente | | string \| Address | Dirección de respuesta | | string \| Address | En respuesta a | | string | Asunto | | string \| Buffer \| AttachmentLikeObject | Cuerpo en texto plano | | string \| Buffer | Cuerpo en HTML | | string \| Address | Remitente físico (Sender header) | | string \| Buffer | Mensaje raw RFC822 | | 'quoted-printable' \| 'base64' | Codificación del texto | | string \| string[] | Referencias de mensajes anteriores | | string | Codificación del mensaje | | Date \| string | Fecha del mensaje | | Headers | Headers adicionales | | Attachment[] | Archivos adjuntos | | DKIM.Options | Opciones de firma DKIM | | string | Nombre del template a renderizar | | { [name: string]: any } | Variables de contexto para el template | | string | Nombre del transportador (para configuración multi-transporter) |

`MailerOptions`

| Campo | Tipo | Descripción | | ---------------------- | ---------------------------------------------------------------------- | ------------------------------------------ | | transport | TransportType | Configuración del transporte único | | transports | { [name: string]: SMTPTransport \| SMTPTransport.Options \| string } | Múltiples transportadores nombrados | | defaults | Options | Opciones por defecto para todos los envíos | | template.dir | string | Directorio de templates | | template.adapter | TemplateAdapter | Adaptador de template | | template.options | object | Opciones adicionales del adaptador | | options.partials.dir | string | Directorio de partials Handlebars |

`TemplateAdapterConfig`

| Campo | Tipo | Default | Descripción | | ------------------ | --------- | ------- | -------------------------------------- | | inlineCssEnabled | boolean | true | Habilita el inlining de CSS en el HTML | | inlineCssOptions | Options | {} | Opciones de @css-inline/css-inline |

Adaptadores exportados

| Clase | Peer dep requerida | Constructor | | ------------------- | ----------------------- | ------------------------------------------ | | HandlebarsAdapter | handlebars (incluida) | new HandlebarsAdapter(helpers?, config?) | | EjsAdapter | ejs (incluida) | new EjsAdapter(config?) | | PugAdapter | pug (incluida) | new PugAdapter(config?) |

Constantes exportadas

| Constante | Valor | Descripción | | -------------------------- | ------------------------------------ | ---------------------------------- | | MAILER_OPTIONS | 'MAILER_OPTIONS' | Token de inyección de opciones | | MAILER_TRANSPORT_FACTORY | 'MAILER_TRANSPORT_FACTORY' | Token de la factory de transporte | | defaultTransportOptions | { secure: true, requireTLS: true } | Opciones de transporte por defecto |

📄 Changelog

Todos los cambios notables de este paquete se documentarán en el archivo Changelog.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme