@weaponsforge/sendemail

NPM library for sending text and HTML emails using Gmail SMTP with Google OAuth2.

CLI Available

• Run via npx (no installation required)

  • Requirements: NodeJS LTS v24.11.0 or later
  • Run npx @weaponsforge/sendemail --help

• Pre-compiled Windows binaries Pre-compiled Windows binaries are available for download in the latest Releases download page.

• Docker image A Docker image is available at https://hub.docker.com/r/weaponsforge/sendemail

Table of Contents

• Requirements
• Quickstart
• Code Samples

📋 Requirements

1. NodeJS LTS v24.11.0 or higher

   Recommended:
   node: 24.11.0
   npm: 10.9.2

2. Gmail Account
   • Google Cloud Platform project configured with OAuth2 settings and credentials
   • Read on the Google Gmail, SMTP and OAuth2 Setup sections for more information

Core Libraries/Frameworks

(Installed via npm)

1. googleapis v171.4.0 - Manages Gmail token access
2. nodemailer v8.0.1 - Sends emails using various transport options
3. commander v14.0.3 - CLI library
4. sanitize-html v2.17.1 - Sanitizes WYSIWYG HTML input
5. zod v3.24.2 - Run-time input validation
6. ejs v4.0.1 - Composes HTML with dynamic text content

Contributing

We welcome contributions! Please see CONTRIBUTING.md and the CODING STYLE for guidelines.

🆕 Quickstart

1. Install the library.

   npm i @weaponsforge/sendemail

2. Set up the environment variables. Create a .env file in your root project directory with the following:

   | Variable Name | Description | | --- | --- | | GOOGLE_USER_EMAIL | Your Google email that you've configured for Gmail SMTP and Google OAuth2. | | GOOGLE_CLIENT_ID | Google OAuth2 client ID linked with your Google Cloud Platform project. | | GOOGLE_CLIENT_SECRET | Google OAuth2 client secret associated with the GOOGLE_CLIENT_ID. | | GOOGLE_REDIRECT_URI | Allowed Google API redirect URI. Its value is https://developers.google.com/oauthplayground by default. | | GOOGLE_REFRESH_TOKEN | The initial (or any) refresh token obtained from the OAuthPlayground.Read on Using the OAuth 2.0 Playground for more information about generating a refresh token using the Google OAuth Playground.(⚠️ INFO: This is an older note; some steps may vary this 2025) |

3. Send emails programmatically via code. See the examples under the Code Samples section for more information.

🧾 Code Samples

A. Send a Text-format Email

import { send } from '@weaponsforge/sendemail'

const main = async () => {
   await send({
      recipient: '[email protected]',
      subject: 'Test Message',
      content: 'How are you?'
   })
}

main()

B. Send an HTML-format Email

import { buildHtml, send } from '@weaponsforge/sendemail'

const emails = ['[email protected]', '[email protected]']

const main = async () => {
   // Build the HTML email content
   const emailContent = await buildHtml({
      content: ['Lorem ipsum dolor sit amet...', 'paragraph #2', 'paragraph #3'],
      recipients: emails,
      sender: process.env.GOOGLE_USER_EMAIL
   })

   // Send the email
   await send({
      subject: 'Welcome Aboard!',
      content: emailContent,
      recipients: emails,
      isHtml: true
   })
}

main()

C. Extend Classes

These are classes that manage the email-sending processes and configurations.

// Sends emails using a Nodemailer transporter
import { EmailSender } from '@weaponsforge/sendemail'

// Initializes the Nodemailer transport with Google OAuth2
import { EmailTransport } from '@weaponsforge/sendemail'

// Manages API keys, methods and properties of the Google `OAuth2Client`
import { GmailOAuthClient } from '@weaponsforge/sendemail'

// Wrapper around `ZodObject` and `ZodEffects` zod schemas
import { SchemaValidator } from '@weaponsforge/sendemail'

// eg., extend (or override) the EmailSender class
class MyOAuthClient extends GmailOAuthClient {
  sayHello (name = '') {
    console.log(`Hello, ${name}!`)
  }
}

const client = new MyOAuthClient()

const token = await client.getAccessToken()
client.sayHello('Tester')

References

• Gmail API [1] [2]
• Gmail Quickstart [3]
• AMP for Gmail [4]
• Google Workspace Guide [5]

@weaponsforge 20260225