GitHub - weaponsforge/send-email: NPM CLI and library for sending text and HTML emails using Gmail SMTP with Google OAuth2

@weaponsforge/sendemail

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

Tip

Run via npx (no installation required)
- Requirements: NodeJS LTS v24.11.0 or later
- Run npx @weaponsforge/sendemail --help
Node.js package
A Node.js package is available at https://www.npmjs.com/package/@weaponsforge/sendemail
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

📋 Requirements

👉 Click to expand the list of requirements

Windows 11/Linux OS
NodeJS LTS v24.11.0 or higher
```
Recommended:
node: 24.11.0
npm: 11.6.1
```
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)

googleapis v171.4.0 - Manages Gmail token access
nodemailer v8.0.1 - Sends emails using various transport options
typescript v5.9.3 - Compile-time error checker
tsx v4.21.0 - Runs TS files in development mode
vitest v4.0.18 - Runs tests
commander v14.0.3 - CLI library
sanitize-html v2.17.1 - Sanitizes WYSIWYG HTML input
zod v3.24.2 - Run-time input validation
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

Create a .env file in the /app directory, replacing the contents of the .env.example file with actual values.
- See Installation # 4 for more information about these environment variables.
Install dependencies.
```
cd app
npm install
```
Transpile to JavaScript.
```
npm run transpile
```
Send a text email using the CLI, eg. using Bash:
```
npm run sendemail -- text \
  -s "You are Invited" \
  -c "Birthday party in December" \
  -r a@gmail.com,b@gmail.com,c@gmail.com
```
💡 TIP: Use sendemail:dev to work on development mode without needing to run "npm run transpile"

Send a styled HTML email using the CLI, eg. using Bash:

npm run sendemail -- html \
  -s "Reading Materials" \
  -c "Lorem ipsum dolor sit amet" "this is paragraph 1" "this is paragraph 2" \
  -r test@gmail.com,one@gmail.com,two@gmail.com

💡 TIP: No transpilation needed with "sendemail:dev"

Send WYSIWYG HTML content using the CLI, eg. using Bash:
(Adjust @/utils/config/sanitizeHtml.ts to allow more styles.)

npm run sendemail -- html \
  -s "WYSIWYG Email" \
  -w "<div style='width:100px; height:100px; border:5px solid blue; border-radius: 3px; padding: 8px; text-align: center; background-color: azure;'><h3>Hello, World</h3></div>" \
  -r "tester@gmail.com"

💡 TIP: Development mode via "sendemail:dev" skips transpilation

🛠️ Installation

Clone the repository.
git clone https://github.com/weaponsforge/send-email.git
Install dependencies.
npm install
Configure OAuth2. Get a refresh token from the Google OAuth 2 Playground.
- 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 in 2025)

Set up the environment variables. Create a .env file inside the /app directory with reference to the .env.example file.

👉 Click to view the environment variable definitions

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)*

🚀 Usage

Using Node

Run a non-test TypeScript file inside the /app/src directory from the project's "root directory". For example:
```
cd app
npx tsx src/utils/sample.ts
```
Run compiled JavaScript code from the TypeScript files. For example:
```
cd app
npm run transpile
node dist/utils/sample.js
```
See the Available Scripts section for more information.

⚡Alternate Usage

Using Docker

Build the image (Run only once)
```
docker compose build --no-cache
```
Run the container (Run only once)
```
docker compose up
```
Run an NPM script using Docker compose
Ensure the Docker container is running (see Run the container)
```
docker exec -it weaponsforge-sendemail-dev <AVAILABLE_SCRIPT_OR_DOCKER_SCRIPT>
```

Run an NPM script using only Docker
Ensure the Docker container is running (see Run the container)

docker run -it -v ${pwd}/app:/opt/app -v /opt/app/node_modules --rm weaponsforge/sendemail:dev <AVAILABLE_SCRIPT_OR_DOCKER_SCRIPT>

Run a non-test TS file using TypeScript Execute (tsx)
(requires Run an NPM script using Docker compose)
```
docker exec -it weaponsforge-sendemail-dev npx tsx /opt/app/src/<PATH_TO_TS_FILE>.ts
```
See the Available Scripts and Docker Scripts sections for more information.

🧾 Code Samples

Send a Text-format Email

app/src/demo/sendEmail.ts

import { send } from '@/lib/index.js'

const main = async () => {
   await send({
      recipient: 'tester@gmail.com',
      subject: 'Test Message',
      content: 'How are you?'
   })
}

main()

Send an HTML-format Email

app/src/demo/sendHtml.ts

import { buildHtml, send } from '@/lib/index.js'

const emails = ['tester@gmail.com', 'admin@gmail.com']

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()

📜 Available Scripts

These scripts, compatible with running in Node and Docker, run various TypeScript scripts and tests.

👉 Click to expand the list of available scripts

A. Running the Codes ⚙️➡️

`npm run dev`

Runs vitest in watch mode, watching file changes and errors to files linked with *.test.ts files.

`npm run watch`

Watches file changes in .ts files using the tsc --watch option.

`npm run transpile`

Builds JavaScript, .d.ts declaration files, and map files from the TypeScript source files in the /src directory.

`npm run transpile:noemit`

Runs type-checking without generating the JavaScript or declaration files from the TypeScript files in the /src and __tests__ directories.

B. Testing 🚦✅

`npm run lint`

Lints TypeScript source codes.

`npm run lint:fix`

Fixes lint errors in TypeScript files.

`npm test`

Runs test scripts defined in *.test.ts files with coverage.
Generates a vitest test report into the /html directory.
Run npm run report:view to preview the generated report.

`npm run test:ui`

Runs test scripts defined in *.test.ts files with coverage.
Spawns a local report-like website showing each test's real-time status and coverage using vitest-ui
This script is similar to the vitest npm run dev script that watches for changes in the *.test.ts files but displays the result logs and coverage details in the local website rather than the command line.

`npm run report:view`

NOTE: This script requires running npm test first to generate a test report into the /html directory

Spins up a local web server accessible at http://localhost:4174/
Serves the website contents of a test report from the /html directory

`npm run copy:files`

Copies the EJS email template into the /dist/templates directory.

This script runs automatically after "npm run transpile", copying the "/app/src/templates/email.ejs" to the "/dist/templates" directory.

`npm run info`

Logs the installed Node.js and npm version, environment platform, architecture and V8 version.

C. CLI 💻

`npm start`

Shorthand for "npm run sendemail"

`npm run sendemail`

Sends text and HTML emails using the command line interface (CLI) with transpiled JavaScript.

💡 IMPORTANT:

This script requires running the "npm run transpile" script before usage.

If you want to run these without transpiling, append a :dev after the NPM script: "npm run sendemail:dev"

CLI Usage

To view the list of available commands: npm run sendemail help

Usage: sendemail [options] [command]

CLI for sending text and HTML emails using Gmail SMTP and Google OAuth2

Options:
-V, --version   output the version number
-h, --help      display help for command

Commands:
text [options]  Send raw text email to one or multiple recipient/s
html [options]  Send paragraphs of text or WYSIWYG content as styled
                  HTML email to one or multiple recipient/s.
help [command]  display help for command

Append a double dash -- to pass arguments to the CLI commands eg., (using Bash)

npm run sendemail -- text \
  -s "You are Invited" \
  -c "Birthday party in December" \
  -r a@gmail.com,b@gmail.com,c@gmail.com

View available options for the sendemail text [options] command.

# Usage options for the send "text" email command
npm run sendemail help text

Usage: sendemail text [options]

Send raw text email to one or multiple recipient/s

Options:
-s, --subject <title>      email subject or title enclosed in double-quotes
-c, --content <text>       email text content enclosed in double-quotes
-e, --env [path]           path to .env file (optional)
-r, --recipients <emails>  comma-separated list of email addresses
-h, --help                 display help for command

View available options for the sendemail html [options] command.

# Usage options for the send "html" email command
npm run sendemail help html

Usage: sendemail html [options]

Send paragraphs of text or WYSIWYG content as styled
HTML email to one or multiple recipient/s.

Options:
-s, --subject <title>      email subject or title enclosed in double-quotes
-r, --recipients <emails>  comma-separated list of email addresses
-c, --content <text...>    whitespace-delimited text/paragraphs enclosed in double-quotes
-w, --wysiwyg [html]       optional HTML tags that form a WYSIWYG content enclosed in double-quotes, using inline CSS styles
-e, --env [path]           path to .env file (optional)
-h, --help                 display help for command

`npm run sendemail:dev`

Sends an email using the command line interface (CLI) in development mode using TypeScript.
Append a double dash -- to pass arguments to the CLI commands.
Usage: view the "npm run sendemail" script for more information. They share similar usage.
- 💡 NOTE: Append :dev in the script eg., npm run sendemail:dev

📦 Docker Scripts

These scripts allow optional Docker-related processes, such as enabling file watching in Docker containers running in Windows WSL2 and others.

Tip

Scripts with a ":win" suffix indicate compatibility for Windows Docker running in WSL2.

👉 Click to expand the list of available scripts

Docker run command

Run the Docker containers first using options A or B.

A. Using Docker compose

docker compose build
docker compose up

Use the template:

docker exec -it weaponsforge-sendemail-dev <AVAILABLE_DOCKER_SCRIPT>

B. Using Only Docker (PowerShell)

docker run -it -v ${pwd}/app:/opt/app -v /opt/app/node_modules --rm weaponsforge/sendemail:dev <AVAILABLE_DOCKER_SCRIPT>

Scripts

`npm run docker:debug`

Runs the "/src/utils/sample/sample.ts" script in containers with debugging enabled in VSCode by default.
Replace the "/src/utils/sample/sample.ts" file path in the package.json file's "docker:debug" script with a target TypeScript file for debugging.
Map port 9229 to enable debugging VSCode while running in Docker (PowerShell).
- (A. Using Docker compose):
  docker exec -it weaponsforge-sendemail-dev npm run docker:debug
- (B. Using Only Docker (PowerShell))
  docker run -it -v ${pwd}/app:/opt/app -v /opt/app/node_modules -p 9229:9229 --rm weaponsforge/sendemail:dev npm run docker:debug

Launch the VSCode debugger using the following configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Docker",
      "address": "localhost",
      "port": 9229,
      "restart": true,
      "skipFiles": ["<node_internals>/**"],
      "localRoot": "${workspaceFolder}/app",
      "remoteRoot": "/opt/app"
    }
  ]
}

`npm run docker:test:ui`

Docker command counterpart of the npm run test:ui script, compatible with containers running in Linux OS.
Runs test scripts defined in *.test.ts files in watch mode with coverage from a container.
Spawns a local report-like website showing each test's real-time status and coverage using vitest-ui accessible at http://localhost:51204/__vitest__/.

`npm run docker:report:view`

NOTE: This script requires running npm test first to generate a test report into the /html directory

Docker command counterpart of the npm run report:view script.
Spins up a local web server accessible at http://localhost:4174/
Serves the website contents of a test report from the host's /html directory

`npm run docker:watch:win`

Watches file changes in .ts files using the tsc --watch option with dynamicPriorityPolling in Docker containers running in Windows WSL2.

`npm run docker:dev:win`

Sets and exports the environment variables: CHOKIDAR_USEPOLLING=1 and CHOKIDAR_INTERVAL=1000
Runs vitest in watch mode inside Docker containers running in Windows WSL2, watching file changes and errors to files linked with *.test.ts files.

`npm run docker:test:ui:win`

Sets and exports the environment variables: CHOKIDAR_USEPOLLING=1 and CHOKIDAR_INTERVAL=1000
Runs test scripts defined in *.test.ts files in watch mode with coverage inside Docker containers running in Windows WSL2.
Spawns a local report-like website showing each test's real-time status and coverage using vitest-ui accessible at http://localhost:51204/__vitest__/.

🏗️ Building the Windows Executable File

This project packages the CLI app into a Windows (.exe) Node Single Executable Application (SEA) file into "/app/build/sendemail.exe" using esbuild and postject.

Using Node

Run the Bash script using GitBash when working in a Windows OS.

chmod u+x ./app/scripts/build-sea-win.sh
./app/scripts/build-sea-win.sh

Using Docker

These steps need to have the Docker container up and running first ("docker compose up").

docker exec -it weaponsforge-sendemail-dev sh ./scripts/build-sea-win.sh

Using the Executable File

Refer to Available Scripts - C. CLI for CLI argument syntax. When running the executable directly, invoke it without npm (no "--" needed), for example:
```
sendemail text -s "You are Invited" -c "Birthday party" -r a@gmail.com,b@gmail.com
```

🚀 Usage with GitHub Actions

Deployment to Docker Hub

This repository deploys the latest development Docker image weaponsforge/sendemail to Docker Hub on the creation of new Tags/Releases from the main branch with GitHub Actions. Supply the following GitHub Secrets and Variable to enable deployment to Docker Hub. It requires a Docker Hub account.

The Docker Hub image is available at:

https://hub.docker.com/r/weaponsforge/sendemail

GitHub Secrets and Variables

GitHub Secrets

GitHub Secret Name	Description
DOCKERHUB_USERNAME	Docker Hub username
DOCKERHUB_TOKEN	Deploy token for the Docker Hub account

GitHub Variables

GitHub Variable Name	Description
DOCKERHUB_USERNAME	Docker Hub username

References

Gmail API ^{[1] [2]}
Gmail Quickstart ^[3]
AMP for Gmail ^[4]
Google Workspace Guide ^[5]

@weaponsforge
20250323

Name		Name	Last commit message	Last commit date
Latest commit History 180 Commits
.github		.github
app		app
docs		docs
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

@weaponsforge/sendemail

Table of Contents

📋 Requirements

Core Libraries/Frameworks

Contributing

🆕 Quickstart

🛠️ Installation

🚀 Usage

Using Node

⚡Alternate Usage

Using Docker

🧾 Code Samples

Send a Text-format Email

Send an HTML-format Email

📜 Available Scripts

A. Running the Codes ⚙️➡️

npm run dev

npm run watch

npm run transpile

npm run transpile:noemit

B. Testing 🚦✅

npm run lint

npm run lint:fix

npm test

npm run test:ui

npm run report:view

npm run copy:files

npm run info

C. CLI 💻

npm start

npm run sendemail

CLI Usage

npm run sendemail:dev

📦 Docker Scripts

Docker run command

Scripts

npm run docker:debug

npm run docker:test:ui

npm run docker:report:view

npm run docker:watch:win

npm run docker:dev:win

npm run docker:test:ui:win

🏗️ Building the Windows Executable File

Using the Executable File

🚀 Usage with GitHub Actions

Deployment to Docker Hub

GitHub Secrets and Variables

GitHub Secrets

GitHub Variables

References

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 7

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`npm run dev`

`npm run watch`

`npm run transpile`

`npm run transpile:noemit`

`npm run lint`

`npm run lint:fix`

`npm test`

`npm run test:ui`

`npm run report:view`

`npm run copy:files`

`npm run info`

`npm start`

`npm run sendemail`

`npm run sendemail:dev`

`npm run docker:debug`

`npm run docker:test:ui`

`npm run docker:report:view`

`npm run docker:watch:win`

`npm run docker:dev:win`

`npm run docker:test:ui:win`

Packages