Google SMTP Email Sender

A simple and reliable npm package for sending emails using Google SMTP with nodemailer. This package provides TypeScript support, proper error handling, and validation for a smooth email sending experience.

Features

• 🚀 Easy to use with Google SMTP
• 📧 Support for text, HTML, and attachments
• 🔒 Built-in validation and error handling
• 📝 Full TypeScript support
• 🔧 Connection verification
• ⚡ Asynchronous API

Installation

npm install @your-org/google-smtp-email-sender

Prerequisites

1. Enable 2-Step Verification on your Google Account
2. Generate an App Password:
   • Go to your Google Account settings
   • Security → 2-Step Verification → App passwords
   • Generate a new app password for your application

Usage

Basic Usage

const GoogleSMTPEmailSender = require('@your-org/google-smtp-email-sender');

const emailSender = new GoogleSMTPEmailSender({
  user: '[email protected]',
  pass: 'your-app-password',
});

async function sendEmail() {
  try {
    const result = await emailSender.sendEmail({
      from: '[email protected]',
      to: '[email protected]',
      subject: 'Hello from our package!',
      text: 'This is a plain text email.',
      html: '<h1>Hello!</h1><p>This is an HTML email.</p>',
    });
    
    console.log('Email sent successfully:', result.messageId);
  } catch (error) {
    console.error('Failed to send email:', error.message);
  }
}

sendEmail();

TypeScript Usage

import GoogleSMTPEmailSender, { EmailConfig, EmailOptions } from '@your-org/google-smtp-email-sender';

const config: EmailConfig = {
  user: '[email protected]',
  pass: 'your-app-password',
};

const emailSender = new GoogleSMTPEmailSender(config);

const emailOptions: EmailOptions = {
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Hello from TypeScript!',
  text: 'This email was sent using TypeScript.',
  html: '<h1>Hello!</h1><p>This email was sent using TypeScript.</p>',
};

emailSender.sendEmail(emailOptions)
  .then(result => console.log('Email sent:', result.messageId))
  .catch(error => console.error('Error:', error.message));

Sending to Multiple Recipients

await emailSender.sendEmail({
  from: '[email protected]',
  to: ['[email protected]', '[email protected]', '[email protected]'],
  subject: 'Group Email',
  text: 'This email is sent to multiple recipients.',
});

Sending Attachments

await emailSender.sendEmail({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Email with Attachments',
  text: 'Please find the attached files.',
  attachments: [
    {
      filename: 'document.txt',
      content: 'This is a text file attachment.',
    },
    {
      filename: 'image.png',
      content: Buffer.from('image-data-here'),
      contentType: 'image/png',
    },
  ],
});

Verifying Connection

try {
  const isConnected = await emailSender.verifyConnection();
  console.log('SMTP connection verified:', isConnected);
} catch (error) {
  console.error('Connection verification failed:', error.message);
}

Closing Connection

// When you're done sending emails, close the connection
await emailSender.close();

API Reference

GoogleSMTPEmailSender

Constructor

constructor(config: EmailConfig)

Parameters:

• config - Configuration object containing:
  • user (string): Your Gmail address
  • pass (string): Your app password

Methods

sendEmail(options: EmailOptions): Promise<SentMessageInfo>

Sends an email using Google SMTP.

Parameters:

• options - Email options object:
  • from (string): Sender email address
  • to (string | string[]): Recipient email address(es)
  • subject (string): Email subject
  • text (string, optional): Plain text content
  • html (string, optional): HTML content
  • attachments (Array, optional): Email attachments

Returns: Promise resolving to nodemailer's SentMessageInfo

verifyConnection(): Promise<boolean>

Verifies the SMTP connection is working.

Returns: Promise resolving to boolean indicating connection status

close(): Promise<void>

Closes the SMTP connection.

Error Handling

The package provides detailed error messages for common issues:

• Authentication errors: Invalid credentials or app password issues
• Connection errors: Network connectivity problems
• Validation errors: Invalid email addresses or missing required fields
• Timeout errors: Connection or socket timeouts

Common Issues and Solutions

"Authentication failed" Error

• Ensure you're using an App Password, not your regular password
• Make sure 2-Step Verification is enabled on your Google Account
• Double-check your email address and app password

"Connection refused" Error

• Check your internet connection
• Verify firewall settings aren't blocking SMTP connections
• Ensure port 587 is accessible

Rate Limiting

Google has sending limits. For bulk emails, consider:

• Implementing delays between sends
• Using email queueing systems
• Upgrading to Google Workspace for higher limits

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please create an issue in the repository.