Gmail Email Forwarding Script

Originally created for Northside Independent School District (NISD). Generalized and released for public use.

A Google Apps Script that forwards all Gmail threads (with attachments) to a personal email address. It tracks progress using a Gmail label to avoid duplicates, handles Apps Script execution time limits gracefully, and supports a dry-run mode for safe testing.

How It Works

1. Searches for all threads without the "Forwarded" label.
2. Forwards every message in each thread to your configured email.
3. Applies the "Forwarded" label so threads aren't processed again.
4. Stops safely before hitting the 6-minute Apps Script time limit and can be re-run to continue.

Setup

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/gmail-forwarding-script.git
cd gmail-forwarding-script

2. Install dependencies (for local testing only)

npm install

3. Configure Clasp

Install the Clasp CLI and authenticate:

npm install -g @google/clasp
clasp login

Create a .clasp.json file in the project root (this file is git-ignored):

{
  "scriptId": "YOUR_SCRIPT_ID_HERE",
  "rootDir": "./src"
}

You can find your scriptId in the Apps Script editor under Project Settings.

4. Set Script Properties

In the Apps Script editor, go to Project Settings → Script Properties and add:

Key	Value
PERSONAL_EMAIL	The email address to forward messages to

5. Push the code

clasp push

6. Authorize the script

1. Open your project at script.google.com.
2. Select forwardEmails from the function dropdown.
3. Click Run.
4. Authorize the Gmail permissions when prompted.

7. Test with a dry run

The script starts in dry-run mode (DRY_RUN = true in src/Code.js). It logs which threads would be forwarded without sending anything. Check the execution log to verify it's picking up the right emails.

8. Forward for real

1. Set DRY_RUN = false in src/Code.js.
2. Push again: clasp push
3. Run forwardEmails from the Apps Script editor.

The script processes threads in batches of 100. If it approaches the time limit, it stops and logs a message — just run it again to continue.

Required Script Properties

Key	Description
PERSONAL_EMAIL	The destination email address for forwarded messages

Optional: Automate with a Trigger

To forward new emails on a schedule:

1. In the Apps Script editor, go to Triggers (clock icon).
2. Click Add Trigger.
3. Set function to forwardEmails, event source to Time-driven, and choose an interval (e.g., every 5 minutes).

Project Structure

gmail-forwarding-script/
├── src/
│   ├── Code.js            # Main script with all functions
│   └── appsscript.json    # Manifest with OAuth scopes and runtime config
├── tests/
│   └── Code.test.js       # Property-based tests for email validation
├── .clasp.json            # Clasp config (git-ignored, contains scriptId)
├── .claspignore           # Controls which files get pushed to Apps Script
├── .gitignore             # Version control exclusions
├── LICENSE                # MIT License
├── package.json           # Node.js dev dependencies (Jest, fast-check)
└── README.md              # This file

OAuth Scopes

Defined in src/appsscript.json:

Scope	Purpose
https://mail.google.com/	Full Gmail access — read, send, and manage emails and labels

Running Tests

npm test

Tests use Jest and fast-check for property-based testing of the email validation logic.

License

MIT — Copyright (c) 2025 Alvaro Gomez