haumdaucher_de/mail_forwarding/AGENTS.md

AGENTS.md

This document provides context for AI agents operating on the mail_forwarding infrastructure in this repository.

Architecture

This directory contains Google Apps Script code configured as Infrastructure as Code (IaC). It automates the creation of email forwarding in Google Workspace by reading from a Google Sheet and dynamically creating/managing Workspace Groups.

Tooling

• We use @google/clasp to manage the deployment of the .js files to Google Apps Script. Note: do NOT write TypeScript as we bypass the local transpilation step.
• The entrypoint is src/Code.js.
• The manifest is src/appsscript.json.

Status

• Current Mode: Active Production (DRY_RUN: false).
• Target: All groups managed by this script are tagged with [Auto-Forwarder] Managed by Google Sheets.

Rules & Safeguards (CRITICAL)

1. Never alter the GROUP_DESCRIPTION_TAG logic. The script achieves declarative state management by finding and deleting Workspace Groups that are NOT present in the Google Sheet. To prevent the catastrophic deletion of real, human-managed groups (e.g., board@haumdaucher.de), the script relies on the [Auto-Forwarder] Managed by Google Sheets string in the group's description. The script must ALWAYS filter for this exact string before issuing any deletion API calls.
2. Always deploy via clasp. Do not instruct the user to copy-paste code manually if clasp is available.
3. Trigger: We use a combination of onFormSubmit (for Google Forms) and onChange (for manual sheet edits) triggers. This ensures reconciliation happens regardless of how the data was updated.
4. Validation Logic: forwardAddress must always be internal (@haumdaucher.de), while forwardToAddress must always be external (non-haumdaucher) to prevent routing loops.