@sologence/nest-js-email-sendgrid NPM

NestJS SendGrid Integration

A robust NestJS module for seamless SendGrid email integration, providing an easy-to-use interface for sending emails using SendGrid's API.

Features

🚀 Easy integration with NestJS applications
📧 Support for template-based emails
🎨 Custom HTML and plain text emails
⚡ Type-safe email parameters
🔒 Secure API key configuration
🎭 Email masking support for secure logging

Installation

npm install @sologence/nest-js-email-sendgrid

Quick Start

Import the module in your app.module.ts. You can use either synchronous registration or async registration:

Synchronous Registration

import { SendgridModule } from '@sologence/nest-js-email-sendgrid';

@Module({
  imports: [
    SendgridModule.register({
      apiKey: 'YOUR_SENDGRID_API_KEY',
      defaultFromEmail: 'your@email.com',
      isGlobal: true, // optional, defaults to false
      masking: true //to enable masking while logging the email default false
    }),
  ],
})
export class AppModule {}

Asynchronous Registration

import { SendgridModule } from '@sologence/nest-js-email-sendgrid';

@Module({
  imports: [
    SendgridModule.registerAsync({
      imports: [ConfigModule], // optional: import modules that are needed for config
      useFactory: async (configService: ConfigService) => ({
        apiKey: configService.get('SENDGRID_API_KEY'),
        defaultFromEmail: configService.get('SENDGRID_FROM_EMAIL'),
        isGlobal: true, // optional, defaults to false
        masking: true //to enable masking while logging the email default false
      }),
      inject: [ConfigService], // optional: services to inject into useFactory
    }),
  ],
})
export class AppModule {}

Inject and use the service in your components:

import { SendgridService } from '@sologence/nest-js-email-sendgrid';

@Injectable()
export class YourService {
  constructor(private readonly sendgridService: SendgridService) {}

  async sendWelcomeEmail(to: string) {
    await this.sendgridService.sendEmailFromTemplate({
      to,
      from: 'your@email.com',
      templateId: 'your-template-id',
      dynamicTemplateData: {
        name: 'John Doe',
      },
    });
  }
}

API Reference

SendgridService Methods

`sendEmailFromTemplate(params: EmailParams)`

Send emails using SendGrid templates.

await sendgridService.sendEmailFromTemplate({
  to: 'recipient@example.com',
  from: 'sender@example.com',
  templateId: 'template-id',
  dynamicTemplateData: {
    // Your template variables
  },
});

`sendEmailCustomHtmlBody(params: EmailParams)`

Send emails with custom HTML content.

await sendgridService.sendEmailCustomHtmlBody({
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Hello',
  html: '<h1>Hello World!</h1>',
});

`sendEmailCustomText(params: EmailParams)`

Send plain text emails.

await sendgridService.sendEmailCustomText({
  to: 'recipient@example.com',
  from: 'sender@example.com',
  subject: 'Hello',
  text: 'Hello World!',
});

Sending Emails with S3 Attachments

The module now supports sending emails with attachments directly from S3 URLs using Nodemailer transport:

// Inject the service
constructor(private readonly sendgridService: SendgridService) {}

// Send email with S3 attachment
await this.sendgridService.sendEmailWithS3Attachment({
  to: 'recipient@example.com',
  from: 'sender@example.com', // optional if defaultFromEmail is set
  subject: 'Document Attached',
  text: 'Please find the attached document',
  url: 'https://your-bucket.s3.amazonaws.com/path/to/file',
  fileName: 'document.pdf' // optional, defaults to 'attachment'
});

S3 Attachment Parameters

Parameter	Type	Required	Description
to	string \| string[]	Yes	Recipient email address(es)
from	string	No	Sender email address (falls back to defaultFromEmail)
subject	string	Yes	Email subject
text	string	Yes	Email body text
url	string	Yes	Full URL to the S3 file
fileName	string	No	Custom filename for the attachment

Response

The method returns a Promise that resolves to the Nodemailer send result object.

Configuration Options

Option	Type	Description
apiKey	string	Your SendGrid API key
defaultFrom	string?	Default sender email address
sandboxMode	boolean?	Enable SendGrid sandbox mode
masking	boolean?	Enable email masking in logs

Error Handling

The service throws typed errors that you can catch and handle:

try {
  await sendgridService.sendEmailFromTemplate(params);
} catch (error) {
  if (error instanceof SendGridError) {
    // Handle SendGrid specific errors
  }
  // Handle other errors
}