Gmail to Discord Email Forwarder

This Node.js application forwards unread Gmail emails to a Discord channel using webhooks. It runs as a background service with automatic restart capabilities.

Prerequisites

• Node.js installed
• A Gmail account
• A Discord server with webhook URL
• Google Cloud Project with Gmail API enabled
• PM2 (Process Manager) - will be installed automatically

Setup

1. Clone this repository

2. Install dependencies:

   npm install

3. Set up Google Cloud Project and Gmail API:

   • Follow the detailed instructions in GOOGLE_CREDENTIALS_SETUP.md
   • This guide will walk you through:
     • Creating a Google Cloud Project
     • Enabling Gmail API
     • Setting up OAuth consent screen
     • Creating and downloading credentials
     • Configuring the application
   • Important: After downloading the credentials from Google Cloud Console, save them as credentials.json in the project root directory

4. Create a Discord webhook:

   • In your Discord server, go to Server Settings > Integrations > Webhooks
   • Create a new webhook
   • Copy the webhook URL

5. Configure environment variables:

   • Copy .env.example to .env
   • Fill in your Gmail API credentials and Discord webhook URL:

     GMAIL_CLIENT_ID=your_client_id
     GMAIL_CLIENT_SECRET=your_client_secret
     DISCORD_WEBHOOK_URL=your_discord_webhook_url
     CHECK_INTERVAL=5
     

Running as a Service

The application uses PM2 process manager to run as a background service with automatic restart capabilities.

1. Start the service:

   chmod +x start.sh
   ./start.sh

2. Common PM2 commands:

   # View logs
   pm2 logs gmail-discord-forwarder
   
   # Monitor service
   pm2 monit gmail-discord-forwarder
   
   # Check status
   pm2 status
   
   # Stop service
   pm2 stop gmail-discord-forwarder
   
   # Restart service
   pm2 restart gmail-discord-forwarder
   
   # View error logs
   tail -f logs/error.log
   
   # View output logs
   tail -f logs/output.log

Features

• Automatic email checking every 5 minutes (configurable)
• Forwards unread emails to Discord channel
• Marks forwarded emails as read
• Auto-restart on crashes or errors
• Comprehensive error logging
• Memory monitoring and management
• Graceful shutdown handling
• Persistent authentication token management

Configuration

You can modify the following in .env:

• CHECK_INTERVAL: Time in minutes between email checks (default: 5)
• GMAIL_CLIENT_ID: Your Google Cloud OAuth client ID
• GMAIL_CLIENT_SECRET: Your Google Cloud OAuth client secret
• DISCORD_WEBHOOK_URL: Your Discord webhook URL

Service configuration in ecosystem.config.js:

• max_restarts: Maximum number of restarts (10)
• min_uptime: Minimum uptime before considering app running (10s)
• max_memory_restart: Restart if memory exceeds limit (1GB)
• restart_delay: Delay between restarts (4000ms)

Logs

Logs are stored in the logs directory:

• error.log: Error messages and stack traces
• output.log: General application output

Security Notes

• Keep your .env file and credentials.json secure
• Never commit these files to version control
• Regularly rotate your Discord webhook URL if compromised
• For detailed security best practices, see GOOGLE_CREDENTIALS_SETUP.md

Troubleshooting

If you encounter any issues:

1. Check the Google credentials setup guide for authentication issues
2. Verify your Discord webhook URL is correct
3. Ensure your Gmail account has unread emails to forward
4. Check the logs in the logs directory
5. Make sure credentials.json exists in the project root directory
6. Check PM2 status and logs for service-related issues

Auto-start on System Boot

PM2 can be configured to start the service automatically on system boot:

pm2 startup
pm2 save