haumdaucher_de/mail_forwarding

Mail Forwarding Automation

This directory contains an Infrastructure-as-Code (IaC) deployment for Google Apps Script. It automates the creation and synchronization of Google Workspace mail forwarding by reading from a Google Sheet (typically populated by Google Forms) and managing Workspace Groups.

Prerequisites

To deploy this code to your Google Workspace, you need the following installed on your machine:

• Node.js & npm
• Google Clasp CLI: Run npm install -g @google/clasp

Step 1: Authentication & Setup

Before you can deploy, you must authenticate your local machine with your Google Workspace Admin account and enable the Apps Script API.

1. Enable the API: Go to https://script.google.com/home/usersettings and turn ON the "Google Apps Script API".
2. Login: In your terminal, run:

   clasp login
   

   This will open a browser window. Sign in with your Workspace Admin account (@haumdaucher.de) and grant the necessary permissions.

Step 2: Configuration

You must configure the script to point to your specific Google Sheet. Open src/Code.js and modify the CONFIG block at the top of the file:

const CONFIG = {
  // 1. The ID of the Google Sheet (found in the URL: https://docs.google.com/spreadsheets/d/<THIS_ID>/edit)
  SPREADSHEET_ID: "YOUR_SHEET_ID_HERE", 
  
  // 2. The name of the tab at the bottom of the screen
  SHEET_NAME: "Form Responses 1",
  
  // 3. The column numbers containing the data (1 = A, 2 = B, 3 = C, etc.)
  COL_SOURCE_ADDRESS: 2, 
  COL_DESTINATION_ADDRESS: 6, 
  
  // 4. Your admin email for receiving reports
  ADMIN_EMAIL: "admin@haumdaucher.de",
  
  // 5. Dry run mode. If true, script logs intended changes without modifying Workspace.
  DRY_RUN: true,
  
  // ... leave the GROUP_DESCRIPTION_TAG untouched!
};

Step 3: Deployment

Once configured, you need to create an Apps Script project in your Google Account and push this code to it.

1. Navigate to this mail_forwarding directory in your terminal.
2. Initialize the project as a standalone script:

   clasp create --type standalone --title "Haumdaucher Mail Forwarding" --rootDir ./src
   

   (This creates a hidden .clasp.json file linking this directory to the cloud project).
3. Push the code:

   clasp push
   

Step 4: Initialization

The code is now in the cloud, but the background triggers need to be activated and the Admin SDK authorized.

1. Open the project in your browser:

   clasp open-script
   

2. Ignore the large blue "Deploy" button. You do not need to create a deployment. This script runs via background triggers, not as a web app.
3. In the toolbar directly above the code editor, look for a dropdown menu showing function names (it might currently say syncForwardings). Click the dropdown and select setup.
4. Click the Run button (the play icon) right next to the dropdown.
5. Authorization Required: Google will prompt you to review permissions. (Note: This interactive browser consent screen is a strict Google Workspace security requirement for scripts accessing the Admin API, which is why this specific step cannot be automated via CLI).
   • Click "Review Permissions"
   • Choose your Admin account.
   • Click "Advanced" -> "Go to Haumdaucher Mail Forwarding (unsafe)"
   • Click "Allow" to grant access to the Admin Directory API, Gmail API, and Google Sheets.
6. Once authorized, the setup function will finish executing. It installs the background onChange trigger.

Step 5: Going Live

By default, the CONFIG block has DRY_RUN: true. This means the script will parse the sheet, output exactly what it intends to do to the logs, and email you a report, but it will not actually create, modify, or delete any Google Workspace Groups.

Once you have reviewed the dry-run execution logs and verified that the script correctly parses all rows and maps the email addresses as you expect:

1. Open src/Code.js and change DRY_RUN: true to DRY_RUN: false.
2. Run clasp push in your terminal to deploy the update.
3. Edit the spreadsheet one more time to trigger the live sync.

You are done! Whenever a new response is submitted to the configured Google Sheet via Forms, the script will automatically run in the background, reconcile the forwarding groups, and send you an email report.

Troubleshooting & Analysis

If you find that the script is not triggering when a new form is submitted:

1. Check Executions: Run clasp open-script and click on the Executions tab (the list/bullet icon) in the left sidebar.
   • No entries? The trigger never fired. You may need to run the setup() function again to ensure the triggers are installed.
   • Failed entries? Click on the failed execution to see the exact error message and stack trace.
2. Re-Run Setup: If you have pushed new code or changed your Google Account permissions, always re-run the setup function in the Apps Script UI to refresh the background triggers and authorization.
3. Trigger Source: Ensure the Google Sheet you are using is the same one linked to your Google Form. The onFormSubmit trigger only fires on the specific sheet receiving the form responses.