Documentation & User Guide

Welcome to the Mail Merge documentation. This guide walks you through installing, configuring, and operating your own self-hosted mail merge campaign engine directly inside Google Sheets.

1. Installation and Initial Code Setup

To install the Extension in a Google Sheet, follow these manual steps:

1. Open a Google Sheet. Create a header row (e.g. Email, First Name, Company) and populate at least one test contact.
2. In the menu bar, click Extensions > Apps Script.
3. Delete any default code in the editor. Open Code.gs and paste the contents of your script.
4. Click the + icon next to Files, choose HTML, name the file Sidebar, and paste the sidebar interface code.
5. Click the Save Project (disk icon) button.
6. Refresh your spreadsheet. A new menu option **"Mail Merge"** will appear in the toolbar.

2. Deploying the Web App (Required for Tracking)

To track email opens and link clicks, Google Apps Script must act as a server listener. This requires deploying the project as a Web App:

1. In the Apps Script Editor, click **Deploy** > **New deployment** (top-right).
2. Click the gear icon next to "Select type" and select **Web app**.
3. Set the configuration:
   • Execute as: Select "Me (your_email@gmail.com)" so it writes directly to your spreadsheet.
   • Who has access: Select "Anyone" (or *"Anyone, even anonymous"*) so external email clients can load the tracking pixel without logging in.
4. Click **Deploy** and authorize permissions when prompted.
5. Copy the **Web App URL** provided at the end (e.g. `https://script.google.com/macros/s/.../exec`).

In your spreadsheet sidebar, expand **Advanced Tracking Options**, paste the URL into the **Custom Web App URL (Override)** field, and ensure tracking toggles are enabled.

3. Composing Gmail Draft Templates

The Extension uses standard Gmail drafts as templates:

1. Open Gmail and click **Compose** to create a new draft.
2. Use double curly brackets to insert personalization tags: Hello {{First Name}}. Make sure the tag spelling matches your sheet columns exactly.
3. You can add standard hyperlinks to the text. The Extension automatically rewrites links to track clicks if click tracking is enabled.
4. Leave the draft in your Drafts folder (do not send it!).

4. Running Campaigns & Analyzing Metrics

Once set up, launching a campaign is simple:

1. In Google Sheets, click **Mail Merge** > **Start Mail Merge**.
2. Select your Gmail draft and the recipient email column from the dropdowns.
3. Use the **Personalized Preview** box in the sidebar to verify tags look correct. Click **"Send Test Email to Me"** to send a live test to your inbox.
4. Click **Run Mail Merge**. The script dynamically creates the tracking columns in your sheet and sends emails.
5. Click **Refresh** in the Campaign Metrics card to load real-time Sent, Opened, and Clicked metrics.

5. Troubleshooting Common Issues

• Open and Click Tracking are Not Logged

Verify that your Web App is accessible anonymously. Open your Web App URL in an **Incognito browser tab**. If it redirects to a Google Login screen, you did not set **"Who has access"** to **"Anyone"** during deployment. Redeploy a **New Version** with the correct permissions.

• TypeError: Cannot read properties of undefined (reading 'parameter')

This error occurs if you click the **"Run"** button on the `doGet` function directly inside the script editor. `doGet(e)` expects an HTTP request event object `e` and cannot be executed manually. Select `testTrackingOpen` or `testTrackingClick` instead to run simulations.