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

send-email

Sends emails using Gmail SMTP with Google OAuth2 or username/pw.

📋 Requirements

Click to expand the list of requirements

Windows 11/Linux OS
NodeJS LTS v22 or higher
```
Recommended:
node: 22.14.0
npm: 10.9.2
```
Gmail Account
- Gmail email/password
- Optional:
  - 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 v162.0.0
nodemailer v7.0.9
typescript v5.9.3 - Compile-time error checker
vite-node v3.2.4- Runs TS files in development mode
vitest v3.2.4 - Runs tests
commander v14.0.1 - CLI library
sanitize-html v2.17.0 - Sanitizes WYSIWYG HTML input

🆕 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.
```
npm install
```
Transpile to JavaScript.
```
npm run transpile
```

Send a text email using the CLI, eg. using Bash:

npm run send-email -- text \
  -s "You are Invited" \
  -c "Birthday party in December" \
  -r [email protected],[email protected],[email protected]

💡 TIP: Use send-email: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 send-email -- html \
  -s "Reading Materials" \
  -c "Lorem ipsum dolor sit amet" "this is paragraph 1" "this is paragraph 2" \
  -r [email protected],[email protected],[email protected]

💡 TIP: Use send-email:dev to work on development mode without needing to run "npm run transpile"

🛠️ 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 this 2025)

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

Variable Name	Description
GOOGLE_USER_EMAIL	Your google email that you've configured for Gmail SMTP and Google OAuth2
GOOGLE_CLIENT_ID	Google Developer Project ID associated with your email
GOOGLE_CLIENT_SECRET	Client secret for the Google Developer Project 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 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 vite-node 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
```
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 Vite
(requires Run an NPM script using Docker compose)

docker exec -it weaponsforge-sendemail-dev npx vite-node /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: '[email protected]',
      subject: 'Test Message',
      content: 'How are you?'
   })
}

main()

Send an HTML-format Email

app/src/demo/sendHtml.ts

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

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

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

   // Send the email
   await send({
      subject: 'Welcome Aboard!',
      content: emailContent,
      recipients,
      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.

C. CLI 💻

`npm run send-email`

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 send-email:dev"

CLI Usage

To view the list of available commands: npm run send-email help

Usage: send-email [options] [command]

CLI for sending an email 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 send-email -- text \
  -s "You are Invited" \
  -c "Birthday party in December" \
  -r [email protected],[email protected],[email protected]

View available options for the send-email text [options] command.

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

Usage: send-email 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 send-email html [options] command.

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

Usage: send-email 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 list containing text/paragraphs enclosed in double-quotes
-w, --wysiwyg [html]       optional HTML tags that form a WYSIWYG layout enclosed in double-quotes
-e, --env <path>           path to .env file (optional)
-h, --help                 display help for command

`npm run send-email: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 send-email" script for more information. They share similar usage.
- 💡 NOTE: Append :dev in the script eg., npm run send-email: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__/.

References

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

@weaponsforge
20250323

Name		Name	Last commit message	Last commit date
Latest commit History 106 Commits
.github/workflows		.github/workflows
app		app
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml

License

weaponsforge/send-email

Folders and files

Latest commit

History

Repository files navigation

send-email

Table of Contents

📋 Requirements

Core Libraries/Frameworks

🆕 Quickstart

🛠️ Installation

🚀 Usage

⚡Alternate Usage

🧾 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

C. CLI 💻

npm run send-email

CLI Usage

npm run send-email: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

References

About

Topics

Resources