# CalGrid High-deliverability Windows desktop scheduler and batch dispatcher for Google Calendar invitations with anti-spam safeguards. Version: 1.0.2 Documentation: https://docs.vib.tools/calgrid/ ## Pages - [Overview](https://docs.vib.tools/calgrid/) - [Getting Started](https://docs.vib.tools/calgrid/getting-started/) - [System Requirements](https://docs.vib.tools/calgrid/getting-started/system-requirements/) - [Installation](https://docs.vib.tools/calgrid/getting-started/installation/) - [First-Time Setup](https://docs.vib.tools/calgrid/getting-started/first-time-setup/) - [Google API Setup](https://docs.vib.tools/calgrid/getting-started/google-api-setup/) - [Feature Guides](https://docs.vib.tools/calgrid/guides/) - [Interface Overview](https://docs.vib.tools/calgrid/guides/interface-overview/) - [Workspace Tabs](https://docs.vib.tools/calgrid/guides/workspace-tabs/) - [Google Authentication](https://docs.vib.tools/calgrid/guides/google-auth/) - [Event Details](https://docs.vib.tools/calgrid/guides/event-details/) - [Recipients Management](https://docs.vib.tools/calgrid/guides/receivers/) - [Dispatch Controls](https://docs.vib.tools/calgrid/guides/dispatch-controls/) - [Progress Monitoring](https://docs.vib.tools/calgrid/guides/progress-monitoring/) - [Dispatch Modes](https://docs.vib.tools/calgrid/guides/dispatch-modes/) - [Brand Identity](https://docs.vib.tools/calgrid/guides/brand-identity/) - [Drive Attachments](https://docs.vib.tools/calgrid/guides/attachments/) - [Template Tags & Spintax](https://docs.vib.tools/calgrid/guides/template-tags/) - [Bottom Status Bar](https://docs.vib.tools/calgrid/guides/bottom-bar/) - [Debug Diagnostics](https://docs.vib.tools/calgrid/guides/debug-dialog/) - [Offline Test Runner](https://docs.vib.tools/calgrid/guides/offline-test-runner/) - [Workflows](https://docs.vib.tools/calgrid/workflows/) - [Sending Your First Campaign](https://docs.vib.tools/calgrid/workflows/sending-first-campaign/) - [Bulk Recipient Import](https://docs.vib.tools/calgrid/workflows/bulk-import/) - [Multi-Workspace Campaigns](https://docs.vib.tools/calgrid/workflows/multi-workspace/) - [Personalized Invitations](https://docs.vib.tools/calgrid/workflows/personalized-invites/) - [Settings](https://docs.vib.tools/calgrid/settings/) - [Application Settings](https://docs.vib.tools/calgrid/settings/application-settings/) - [Help & Troubleshooting](https://docs.vib.tools/calgrid/help/) - [Troubleshooting Guide](https://docs.vib.tools/calgrid/help/troubleshooting/) - [Frequently Asked Questions](https://docs.vib.tools/calgrid/help/faq/) - [Limitations & Boundaries](https://docs.vib.tools/calgrid/help/limitations/) ## Full documentation # CalGrid — User Documentation **CalGrid** is a Windows desktop application for scheduling and batch-sending Google Calendar invitations at scale. With a multi-workspace interface, smart anti-spam engine, Google Drive attachments, and brand identity tools, CalGrid is built for high-deliverability calendar outreach. --- ## Documentation Sections | Section | Description | |---|---| | [Getting Started](getting-started/index.md) | Installation, setup, and first launch | | [Interface Guide](guides/interface-overview.md) | Understanding the main UI | | [Feature Guides](guides/index.md) | Complete feature reference | | [Workflows](workflows/index.md) | Step-by-step task guides | | [Settings](settings/index.md) | All settings explained | | [Help & Troubleshooting](help/index.md) | Troubleshooting, FAQ, limitations | --- ## Quick Navigation - **New user?** Start with [Getting Started](getting-started/index.md) - **Need Google Calendar setup?** See [Google API Setup](getting-started/google-api-setup.md) - **Sending invites?** See [Sending Your First Campaign](workflows/sending-first-campaign.md) - **Customizing behavior?** See [Settings Reference](settings/application-settings.md) - **Having problems?** See [Troubleshooting](help/troubleshooting.md) --- ## About CalGrid CalGrid v1.0.2 — Google Calendar Dispatcher Product of Vib Tools Workspace Platform: Windows 10/11 (64-bit) Runtime: Python 3.12 + PySide6 (Qt Widgets) # Getting Started Welcome to CalGrid. This section walks you through everything you need to run CalGrid for the first time and connect it to Google Calendar. --- ## Steps 1. **[System Requirements](system-requirements.md)** — Verify your Windows PC meets the requirements 2. **[Installation](installation.md)** — Install CalGrid from source on your Windows PC 3. **[First-Time Setup](first-time-setup.md)** — Activate your license and launch the application 4. **[Google API Setup](google-api-setup.md)** — Create a Google Cloud project and connect your Calendar account --- ## Quick Start Summary ``` Install Python 3.12 → Create venv → Install requirements → Activate license → Set up Google OAuth → Send first campaign ``` If you have already installed CalGrid and want to send your first batch of invitations, go directly to [Sending Your First Campaign](../workflows/sending-first-campaign.md). # System Requirements CalGrid is a native Windows desktop application. The following requirements must be met before installation. --- ## Minimum Requirements | Component | Requirement | |---|---| | **Operating System** | Windows 10 (64-bit) or Windows 11 | | **Python** | Python 3.12 or higher | | **RAM** | 2 GB available | | **Storage** | 500 MB free disk space (for dependencies and virtual environment) | | **Internet** | Required for Google Calendar API and license verification | | **Google Account** | A Google account with access to Google Calendar | | **Google Cloud Project** | Required for OAuth client credentials (see [Google API Setup](google-api-setup.md)) | --- ## Software Requirements | Software | Purpose | |---|---| | **Python 3.12** | Application runtime | | **pip** | Package installation | | **Windows Credential Manager** | Secure token storage (built into Windows — no installation required) | | **Google Chrome or Edge** | Used by the OAuth authorization flow to open the Google sign-in page | --- ## Network Requirements CalGrid requires internet access for: - License verification (on startup and during use) - Google OAuth authorization (once per workspace connection) - Google Calendar API calls (during event dispatch) - Optional: Google Drive API (if using file attachments) CalGrid does **not** require a static IP address or server-side infrastructure. --- ## Supported Platforms | Platform | Support | |---|---| | Windows 10 (64-bit) | ✅ Supported | | Windows 11 (64-bit) | ✅ Supported | | Windows 32-bit | ❌ Not supported | | macOS | ❌ Not supported | | Linux | ❌ Not supported | > **Note:** CalGrid is a Windows-only application. No cross-platform version exists. --- ## Related Pages - [Installation](installation.md) - [First-Time Setup](first-time-setup.md) # Installation CalGrid runs from source using Python. Follow these steps to install and run CalGrid on your Windows PC. --- ## Prerequisites Before installing, ensure you have: - Windows 10 or Windows 11 (64-bit) - Python 3.12 installed ([python.org](https://www.python.org/downloads/)) - CalGrid source files on your computer --- ## Step 1 — Open a Terminal Open **Command Prompt** or **PowerShell** and navigate to the CalGrid folder: ```powershell cd path\to\CalGrid ``` --- ## Step 2 — Create a Virtual Environment ```powershell py -3 -m venv .venv ``` This creates an isolated Python environment inside the `.venv` folder so CalGrid's dependencies do not conflict with other Python programs on your system. --- ## Step 3 — Install Dependencies ```powershell .venv\Scripts\python.exe -m pip install -r requirements.txt ``` This installs all required packages including PySide6 (the UI framework) and the Google API client libraries. The installation may take a few minutes depending on your internet speed. --- ## Step 4 — Run CalGrid After installation, launch CalGrid using either method: **Option A — Command line:** ```powershell .venv\Scripts\python.exe main.py ``` **Option B — Double-click launcher:** Double-click `RUN_CalGrid.bat` in the CalGrid folder. > **Note:** You only need to run Steps 2 and 3 once. After that, use `RUN_CalGrid.bat` or the command in Step 4 to start CalGrid each time. --- ## First Launch On first launch, CalGrid opens the **License Activation** screen. You must enter a valid license key to access the application. See [First-Time Setup](first-time-setup.md) to continue. --- ## Data Storage Location CalGrid stores workspace data, session state, and application settings in: ``` %LOCALAPPDATA%\CalGrid\ ``` This folder is created automatically on first run. Do not delete it while CalGrid is running. --- ## Related Pages - [System Requirements](system-requirements.md) - [First-Time Setup](first-time-setup.md) - [Google API Setup](google-api-setup.md) # First-Time Setup When you launch CalGrid for the first time, you will see the **License Activation** screen before the main application opens. --- ## License Activation Screen CalGrid requires a valid license key to operate. The activation screen appears every time you start CalGrid until a valid license session is established. ### What You See The activation screen shows: - The CalGrid logo and name - A **License Key** input field - A **Show / Hide** toggle for the key - A **Verify License & Continue** button - A status message below the button ### How to Activate 1. Obtain your license key from your seller or distributor. 2. Launch CalGrid — the activation screen appears automatically. 3. Click the **License Key** field and paste your license key. 4. Click **Verify License & Continue** (or press **Enter**). 5. CalGrid connects to the license server to verify your key. 6. When verification succeeds, the main application opens automatically. > **Tip:** Use the **Show** button to reveal the key and confirm you pasted it correctly. --- ## License Status Messages | Message | Meaning | |---|---| | *Enter the license key provided with your purchase.* | Ready — waiting for your key | | *Verifying your license...* | License check is in progress | | *Invalid license key. Please check and try again.* | Key is incorrect or not recognized | | *This license has expired. Please renew to continue.* | Your license subscription has ended | | *Unable to verify. Check your connection and try again.* | Internet connection issue | | *Device limit reached for this license.* | The key has been used on the maximum number of devices | --- ## After Activation Once CalGrid opens, you will see the main workspace. Before sending invitations, you need to connect a Google account to each workspace. See [Google API Setup](google-api-setup.md) for the full Google Calendar connection guide. --- ## License and Session Behavior - CalGrid maintains a live license session while running. Do not block internet access during use. - If the license server becomes temporarily unavailable, CalGrid may enter an **Offline Grace** period — existing sessions remain active for a limited time. - If your license is revoked or expires during use, CalGrid will show a notification and require re-verification on the next launch. - Your license key is **never stored** in any file on disk. It is verified in memory and then discarded. --- ## Related Pages - [Installation](installation.md) - [Google API Setup](google-api-setup.md) - [Troubleshooting — License Issues](../help/troubleshooting.md#license-issues) # Google API Setup CalGrid uses the **Google Calendar API** to create calendar events. Before sending any invitations, you must create a Google Cloud project and connect your Google account. --- ## Overview The setup process has five steps, all in the **Google Cloud Console**: ``` 1. Create a Project → 2. Enable Calendar API → 3. Configure Consent → 4. Create OAuth Client → 5. Download JSON ``` CalGrid includes a **quick-access toolbar** at the bottom of each workspace with clickable buttons that open the correct Google Cloud Console page for each step. --- ## Step 1 — Create or Select a Google Cloud Project 1. Go to [console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate). 2. Create a new project, or select an existing one from the top project menu. 3. Note the project name — you will use it throughout the setup. --- ## Step 2 — Enable the Google Calendar API 1. Go to [console.cloud.google.com/apis/library/calendar-json.googleapis.com](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com). 2. Ensure your project is selected at the top. 3. Click **Enable**. > **Optional — Google Drive API:** If you plan to attach files to invitations, also enable the Google Drive API at [console.cloud.google.com/apis/library/drive.googleapis.com](https://console.cloud.google.com/apis/library/drive.googleapis.com). --- ## Step 3 — Configure the OAuth Consent Screen 1. Go to [console.cloud.google.com/apis/credentials/consent](https://console.cloud.google.com/apis/credentials/consent). 2. Select **External** user type (unless you have Google Workspace). 3. Fill in the required fields: App name, User support email, Developer contact email. 4. Add the required OAuth scopes: - `https://www.googleapis.com/auth/calendar.events` *(Required: creating and dispatching calendar events)* - `https://www.googleapis.com/auth/drive.file` *(Required: uploading and sharing event attachments via Google Drive)* - `https://www.googleapis.com/auth/userinfo.email` and `openid` *(Required: displaying your connected Google email in the app title bar)* 5. Add your own Google account as a **Test user** (required for external apps). 6. Save and continue through all consent screen steps. --- ## Step 4 — Create an OAuth Client ID 1. Go to [console.cloud.google.com/apis/credentials/oauthclient](https://console.cloud.google.com/apis/credentials/oauthclient). 2. For **Application type**, select **Desktop app**. 3. Give it a name (e.g., "CalGrid Desktop"). 4. Click **Create**. > **Important:** Choose **Desktop app**, not Web application. Web application client JSON requires extra callback configuration to work with CalGrid's local OAuth flow. --- ## Step 5 — Download the Client Secret JSON 1. Go to [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials). 2. Find the OAuth 2.0 client you just created. 3. Click the **Download** (⬇) icon on the right. 4. Save the downloaded JSON file somewhere accessible on your computer — for example, your Desktop or Documents folder. > **Keep this file safe.** It contains your app's client credentials. Do not share it publicly or commit it to source control. --- ## Step 6 — Connect CalGrid to Your Google Account 1. Open CalGrid. 2. In the left sidebar of any workspace, find the **Google Auth** section. 3. Click **+ Add** to open a file picker. 4. Select the JSON file you downloaded in Step 5. 5. The button changes to **✓ JSON** when the file is accepted. 6. Click **🔗 Connect**. 7. Your default web browser opens the official Google sign-in page. 8. Sign in with your Google account and grant CalGrid the requested Calendar permissions. 9. After authorization, return to CalGrid — the sidebar shows **🔓 Disconnect** and your account email appears in the title bar. --- ## Service Account JSON (Advanced) CalGrid also accepts **Service Account JSON** files. Service accounts can be useful for automated workflows but have limitations: - Google may restrict calendar invitations sent from service accounts without **Google Workspace domain-wide delegation**. - For personal Google accounts and standard outreach, use a **Desktop OAuth client JSON** (described above). --- ## Reconnecting After Restart CalGrid remembers your OAuth connection across restarts using **Windows Credential Manager**. When you reopen CalGrid: - The sidebar briefly shows **⏳ Verify...** while checking your saved credentials. - If valid: the sidebar shows **🔓 Disconnect** automatically — no re-authorization needed. - If expired or revoked: the sidebar shows **🔗 Connect** — click to re-authorize in your browser. --- ## Disconnecting To disconnect a Google account from a workspace: 1. In the left sidebar, click **🔓 Disconnect**. 2. The stored token is deleted from Windows Credential Manager. 3. The sidebar returns to **🔗 Connect** state. --- ## Related Pages - [Google Auth Guide](../guides/google-auth.md) - [Troubleshooting — Google Auth](../help/troubleshooting.md#google-auth-issues) - [FAQ — Google API](../help/faq.md) # Feature Guides Complete reference for every CalGrid feature and UI element. --- ## Interface | Guide | Description | |---|---| | [Interface Overview](interface-overview.md) | Complete map of the CalGrid window | | [Workspace Tabs](workspace-tabs.md) | Creating, switching, renaming, and closing workspaces | | [Dispatch Modes](dispatch-modes.md) | Safe / Normal / Fast / Ultra modes | | [Bottom Status Bar](bottom-bar.md) | Tags, Debug, Docs, Help, Report, About | --- ## Campaign Setup | Guide | Description | |---|---| | [Google Auth](google-auth.md) | Connecting and managing Google accounts | | [Event Details](event-details.md) | Event name, date/time, location, message | | [Template Tags](template-tags.md) | Dynamic personalization with tags and spintax | | [Receivers](receivers.md) | Adding, importing, and deduplicating recipients | | [Brand Identity](brand-identity.md) | Brand name and calendar customization | | [Attachments](attachments.md) | Attaching files via Google Drive | --- ## Running Campaigns | Guide | Description | |---|---| | [Dispatch Controls](dispatch-controls.md) | Start, Pause, Resume, Stop | | [Progress Monitoring](progress-monitoring.md) | Live stats, progress bar, log panel | --- ## Diagnostics | Guide | Description | |---|---| | [Debug Dialog](debug-dialog.md) | Real-time API diagnostics and log viewer | | [Offline Test Runner](offline-test-runner.md) | Running built-in offline tests | # Interface Overview CalGrid uses a compact, high-density desktop interface. This page explains every area of the main window. --- ## Window Layout ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Title Bar [● ● ●] CalGrid VERIFIED [Safe|Normal|Fast|Ultra] ⚙ │ ├──────────────────────────────────────────────────────────────────────┤ │ [Workspace 1] [Workspace 2] [+] │ ← Tab Bar ├────────────┬─────────────────────────────────────────────────────────┤ │ │ 📅 Event Details │ 📧 Receivers │ │ Sidebar │ Name / Date / Link / Msg │ Upload / Dedupe / List │ │ │ │ ▶ Start ❚❚ Pause ■ Stop │ │ Workspace │─────────────────────────── │────────────────────────────│ │ Google │ Progress │ Stats (Total/Done/Fail) │ │ Advance │ ████████░░ 60% │ │ │ │─────────────────────────── ┴────────────────────────────│ │ │ ⚡ Create Google API: 1.Project 2.Enable 3.Consent… │ ├────────────┴─────────────────────────────────────────────────────────┤ │ 🏷 Tags ● Ready ⚡ Normal Mode ⚡Debug 📄Docs ❓Help ℹ️ v1.0.2│ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## Title Bar The dark title bar at the top of the window contains: | Element | Purpose | |---|---| | **● (red dot)** | Close the application | | **● (yellow dot)** | Minimize to taskbar | | **● (green dot)** | Maximize or restore window size | | **CalGrid logo + name** | Application branding | | **VERIFIED badge** | License status indicator | | **Mode Selector** | Switch dispatch mode (Safe / Normal / Fast / Ultra) | | **● status dot** | Green = Google account connected; Grey = not connected | | **Account email** | Shows connected Google account for active tab | | **⚙ Settings** | Opens the Settings dialog (`Ctrl+,`) | You can **drag the title bar** to move the window. **Double-click** to maximize or restore. --- ## Tab Bar The tab bar below the title bar manages your workspaces. | Element | Purpose | |---|---| | **Workspace tabs** | Each tab is an independent campaign workspace | | **Active tab** | Highlighted with an indigo top border — this is your current workspace | | **× on each tab** | Close that workspace tab | | **+ button** | Create a new workspace tab | | **‹ › arrows** | Scroll through tabs when many are open | Each workspace tab shows an authentication status dot and a live progress badge: - **Connection Dot**: - **Green** (`#16a34a`) — Google account connected and authorized - **Grey** (`#cbd5e1`) — No Google account connected - **Progress Badge** (shown during or after dispatch): - **Amber badge** (e.g., `45%`) — Job is actively running - **Cyan badge** (e.g., `❚❚ 45%`) — Job is currently paused - **Green badge** (`✓`) — Campaign completed successfully - **Red badge** (`✗`) — Campaign was cancelled or stopped When documentation or bug reporting is opened, an integrated **Browser Tab** (with a `🌐` globe icon) appears on the tab bar alongside workspace tabs. --- ## Left Sidebar The 206px sidebar on the left side of each workspace has three sections: ### Workspace Section - **Name field** — editable workspace name (locked during active dispatch) ### Google Auth Section - **+ Add / ✓ JSON** — select your OAuth credential JSON file - **🔗 Connect / 🔓 Disconnect** — authorize or revoke Google Calendar access - **Status indicator** — shows connecting, verifying, or connected state ### Advance Section - **🏷️ Brand Name** — configure brand identity for this workspace - **Brand label** — shown when brand is active (e.g., "● Acme Corp") - **📎 Event Attachment** — attach files via Google Drive - **⚙ (gear icon)** — configure custom attachment display name --- ## Main Content Area The main area has four panels arranged in a 2×2 grid: ### 📅 Event Details (top-left, tall panel) Covers the full left column and contains: - **Name (event title)** — the calendar event title - **Date & Time** — date picker with calendar popup, time in AM/PM format - **Meeting Link / Location** — URL or venue address - **Message (Description)** — rich text invite message with Live Preview and Template Tags ### 📧 Receivers (top-right) - **📁 Upload List** — import emails from CSV/Excel/text files - **✂ Remove Duplicates** — deduplicate the current list - **Email text area** — paste or type recipient emails - **Status counter** — shows number of valid recipients - **▶ Start / ❚❚ Pause / ▶ Resume / ■ Stop** — dispatch control buttons ### 📊 Progress (bottom-right) - Percentage complete - Progress bar - **Total / Done / Fail / Left** stat cards ### ⚡ Google API Quick Setup Bar (bottom, full-width) Five clickable step buttons that open the correct Google Cloud Console pages for initial setup. --- ## Bottom Status Bar The thin dark bar at the very bottom of the window: | Element | Location | Purpose | |---|---|---| | **🏷 Tags** | Left | Open the dynamic tags reference modal | | **● Ready / Working / Paused** | Left-center | Live dispatch status | | **⚡ Normal Mode** | Left-center | Current dispatch mode badge | | **⚡ Debug** | Right | Open diagnostics dialog | | **📄 Docs** | Right | Open documentation in built-in browser | | **❓ Help** | Right | Open help resources | | **🐛 Report** | Right | Open issue reporting | | **ℹ️ About** | Right | Open About dialog with version and shortcuts | | **v1.0.2** | Far right | Application version | --- ## Keyboard Shortcuts | Shortcut | Action | |---|---| | `Ctrl + T` | Create new workspace tab *(Note: About modal cheat sheet lists Ctrl+N, but active runtime shortcut is Ctrl+T)* | | `Ctrl + W` | Close active workspace tab | | `Ctrl + Tab` | Switch to next workspace tab | | `Ctrl + Shift + Tab` | Switch to previous workspace tab | | `Ctrl + ,` | Open Settings dialog | | `Ctrl + B` | Toggle navigation sidebar | | `Ctrl + F` | Focus search bar in Settings dialog | | `Escape` | Dismiss open dialogs and modals (or clear search input) | --- ## Related Pages - [Workspace Tabs](workspace-tabs.md) - [Google Auth](google-auth.md) - [Event Details](event-details.md) - [Receivers](receivers.md) - [Dispatch Controls](dispatch-controls.md) - [Settings Reference](../settings/application-settings.md) # Workspace Tabs CalGrid supports multiple independent workspaces, each running its own campaign with its own Google account, recipient list, event settings, and dispatch state. --- ## Overview Each workspace tab is completely isolated from other tabs. You can: - Run different campaigns simultaneously - Use different Google accounts in each tab - Have different event details and recipient lists per tab - Pause one workspace while another continues running --- ## Creating a New Workspace **Method 1:** Click the **+** button at the right end of the tab bar. **Method 2:** Press `Ctrl + T` *(the primary runtime shortcut; note that About modal lists Ctrl+N)*. A new workspace opens with default settings and an empty recipient list. It is named "Workspace N" where N is the next available number. --- ## Switching Between Workspaces **Method 1:** Click the workspace tab you want. **Method 2:** Press `Ctrl + Tab` (next tab) or `Ctrl + Shift + Tab` (previous tab). When you switch tabs, CalGrid loads the state of the selected workspace — including its event details, recipients, authentication status, and logs. --- ## Renaming a Workspace 1. Click the **Name** field at the top of the left sidebar. 2. Type the new workspace name. 3. The name updates immediately and is saved automatically. > **Note:** The Name field is locked while a dispatch job is running in that workspace. --- ## Closing a Workspace **Method 1:** Click the **×** button on the tab. **Method 2:** Select the tab and press `Ctrl + W`. If a dispatch job is active in a workspace when you close it, CalGrid stops the job before closing. > **Note:** You cannot close the last remaining workspace tab. --- ## Tab Status Indicators Each tab chip displays an account connection indicator and a job progress badge: ### 1. Connection Status Dot (Left of Tab Label) - **Green dot (`#16a34a`)**: Google OAuth account is connected and authorized for this workspace. - **Grey dot (`#cbd5e1`)**: No Google account is currently connected to this workspace. ### 2. Job Progress Badge (Right of Tab Label) When a campaign is started, paused, or completed, an informative badge appears: - **Amber badge** (`{percent}%`): Job is actively dispatching in the background. - **Cyan badge** (`❚❚ {percent}%`): Job is currently paused. - **Green badge** (`✓`): Campaign finished successfully with all batches acknowledged. - **Red badge** (`✗`): Job was cancelled or aborted manually. --- ## Tab Overflow Navigation If you have more workspace tabs than fit in the tab bar, use the **‹** (left arrow) and **›** (right arrow) buttons at the right of the tab bar to scroll through them. You can also use the mouse scroll wheel while hovering over the tab bar. --- ## Workspace Persistence CalGrid automatically saves workspace state: - **On every edit** — a 350ms debounced save fires when you type or change fields - **On application exit** — all workspaces are saved when CalGrid closes - **On crash** — an emergency save fires if CalGrid exits unexpectedly Workspace data is stored in `%LOCALAPPDATA%\CalGrid\workspaces.json`. Receiver text and log entries are encrypted using Windows DPAPI (tied to your Windows user account). --- ## Running Parallel Campaigns You can run dispatch jobs in multiple workspaces simultaneously. Each workspace runs its own background worker thread independently. To run parallel campaigns: 1. Create multiple workspace tabs. 2. Configure each tab with its own Google account, event details, and recipient list. 3. Click **▶ Start** in each tab. Each workspace operates independently. Pausing or stopping one workspace does not affect others. See [Running Parallel Campaigns](../workflows/multi-workspace.md) for a full walkthrough. --- ## Related Pages - [Interface Overview](interface-overview.md) - [Running Parallel Campaigns](../workflows/multi-workspace.md) - [Google Auth](google-auth.md) # Google Account Connection Each CalGrid workspace connects to a separate Google account via OAuth 2.0. This page explains how to connect, verify, and manage your Google account per workspace. --- ## Overview CalGrid uses the official Google Desktop OAuth 2.0 flow to access your Google Calendar. Your account credentials are stored securely in Windows Credential Manager — never in any file on disk. --- ## Connecting a Google Account ### Requirements Before connecting, you need: - A Google Cloud project with the Calendar API enabled - An OAuth 2.0 Desktop client JSON file downloaded from Google Cloud Console If you have not completed this setup yet, see [Google API Setup](../getting-started/google-api-setup.md). ### Connection Steps 1. In the **left sidebar**, find the **Google Auth** section. 2. Click **+ Add** (or **✓ JSON** if a file was previously selected). 3. A file picker opens — navigate to and select your OAuth client JSON file. 4. The button changes to **✓ JSON** and shows the filename on hover. 5. Click **🔗 Connect**. 6. Your default browser opens the Google sign-in page. 7. Sign in with your Google account. 8. Grant CalGrid the requested Calendar permissions when prompted. 9. After authorization, the browser closes or shows a confirmation message. 10. Return to CalGrid — the sidebar now shows **🔓 Disconnect** and the title bar shows your account email with a green dot. --- ## Connection Status Indicators | Sidebar Button Text | Title Bar Dot | Meaning | |---|---|---| | **+ Add** | Grey | No JSON file selected | | **✓ JSON** + **🔗 Connect** | Grey | JSON loaded, not yet authorized | | **⏳ Verify...** | Grey | Checking saved credentials on startup | | **⏳ Wait...** | Grey | OAuth browser flow in progress | | **🔓 Disconnect** | Green (✓ email) | Connected and authorized | --- ## Automatic Credential Restoration When CalGrid starts, it automatically checks saved credentials for every workspace in the background: 1. CalGrid reads the stored OAuth token from Windows Credential Manager. 2. If the token is valid, the workspace is marked connected — no browser prompt required. 3. If the token has expired or was revoked, the workspace shows **🔗 Connect** and you must re-authorize. This check takes a few seconds. The sidebar shows **⏳ Verify...** briefly during this process. --- ## Disconnecting a Google Account 1. In the left sidebar, click **🔓 Disconnect**. 2. The stored token is immediately deleted from Windows Credential Manager. 3. The sidebar returns to **🔗 Connect** state. You can reconnect at any time by clicking **🔗 Connect** again. --- ## Reselecting a JSON File If you need to use a different OAuth JSON file (e.g., after recreating credentials in Google Cloud): 1. Click the **✓ JSON** button in the sidebar. 2. A file picker opens — select the new JSON file. 3. Click **🔗 Connect** to authorize with the new credentials. --- ## Service Account JSON (Advanced) CalGrid accepts **Service Account JSON** files in addition to Desktop OAuth client files. Service accounts require Google Workspace domain-wide delegation to send invitations from other users' calendars. For standard personal Google accounts, always use a **Desktop OAuth client JSON**. --- ## Security Notes - OAuth tokens are stored in **Windows Credential Manager** under the key `CalGrid.OAuth.v1`. - Tokens are tied to your Windows user account and cannot be read by other users on the same machine. - CalGrid never stores your Google password. - Disconnecting removes the stored token permanently. --- ## Related Pages - [Google API Setup](../getting-started/google-api-setup.md) - [Troubleshooting — Google Auth Issues](../help/troubleshooting.md#google-auth-issues) # Event Details The **Event Details** panel is the large left panel in each workspace. It defines the Google Calendar event that will be created for each recipient. --- ## Fields ### Name (Event Title) **What it is:** The title of the Google Calendar event that recipients will see in their calendar. **How to use:** 1. Click the Name field. 2. Type your event title (e.g., "Team Kickoff Meeting", "Product Demo Call"). **Supports template tags:** Yes — you can use dynamic tags like `{name}` in the event title. See [Template Tags](template-tags.md). **Required:** Yes — a name is required before you can start a campaign. --- ### Date & Time **What it is:** The start date and time of the calendar event. **How to use:** 1. Click the **Date & Time** field. 2. The field shows a date/time in `YYYY-MM-DD hh:mm AM/PM` format. 3. Click the small calendar icon on the right of the field to open a date picker popup. 4. Select your date and adjust the time. **Rules:** - The date and time must be in the future. Past dates are not accepted. - CalGrid defaults to the next day at 10:00 AM when no date has been set. - The timezone of the event is determined by your [Default Timezone setting](../settings/application-settings.md#calendar-settings). **Slot Staggering:** When [Slot Stagger](../settings/application-settings.md#advance-settings) is enabled, each recipient's event start time is offset by the configured interval (e.g., +15 minutes per recipient). The `{time}` and `{date}` template tags reflect each recipient's individual staggered time. --- ### Meeting Link / Location **What it is:** An optional URL or physical location for the event. **How to use:** 1. Click the **Meeting Link / Location** field. 2. Type or paste a meeting URL (e.g., `https://meet.google.com/xxx-xxxx-xxx`) or a venue address. **Google Meet links:** To automatically generate a Google Meet link for every event, enable **Auto Generate Meet Link** in [Settings → Invites](../settings/application-settings.md#invitations-settings) instead of entering a manual URL here. --- ### Message (Description) **What it is:** The body text of the calendar invitation — the description that recipients see when they open the event. **How to use:** 1. Click inside the message area. 2. Type your invitation message. 3. Use template tags (e.g., `{name}`, `{spin:Option A|Option B}`) for personalization. **Rich Text & Formatting Toolbar:** The message editor features a compact formatting toolbar: - **Text Styles**: **B** (Bold, `Ctrl+B`), *I* (Italic, `Ctrl+I`), U (Underline, `Ctrl+U`), and ~~S~~ (Strikethrough). - **Lists**: `•≡` (Bulleted list) and `1≡` (Numbered list) with compact spacing. - **Hyperlink Insertion (`🔗`)**: Opens a dialog to attach web links (`https://...`). - **Unicode Font Styler (`Aa ▾`)**: Applies zero-dependency stylized Unicode text (Sans-Serif Bold, Serif Bold, Sans-Serif Italic, Monospace). - **Dynamic Tag Inserter (`⚡ Tag ▾`)**: 1-click dropdown to insert placeholders like `{name}`, `{email}`, `{company}`, `{date}`, `{ref}`, or `{id}` directly at cursor position. **Live Preview (`👁 Live Preview`):** Opens an interactive Google Calendar invitation simulation dialog (`CalendarPreviewDialog`). It displays the exact card recipients will see, including the organizer brand, date badge, location, and description. You can switch between different sample recipients using the top dropdown menu to test how dynamic tags and spintax expand. **Template Tags (`Template tags`):** Opens the comprehensive dynamic tags modal dialog (`TagsDialog`) with 1-click clipboard copy. --- ## Field Lock During Dispatch All Event Details fields are **locked (read-only) while a campaign is running**. You cannot change the event name, date, or message during an active job. To modify event details, [stop the current job](dispatch-controls.md) first, then edit the fields and start a new campaign. --- ## Related Pages - [Template Tags](template-tags.md) - [Dispatch Controls](dispatch-controls.md) - [Settings — Calendar](../settings/application-settings.md#calendar-settings) # Receivers The **Receivers** panel manages your list of recipient email addresses. CalGrid creates one Google Calendar event per recipient. --- ## Overview Receivers are the people who will receive your Google Calendar invitation. Each email address in the list gets its own individual calendar event with that person as an attendee. --- ## Adding Recipients ### Method 1 — Type or Paste Directly Click inside the recipient text area and type or paste email addresses. Accepted formats: ``` john@example.com jane@example.com, alice@company.org bob@work.com; carol@domain.net ``` CalGrid accepts: - One email per line - Comma-separated emails - Semicolon-separated emails - Mixed formats Invalid email addresses are silently skipped when the job starts. --- ### Method 2 — Upload a File Click **📁 Upload List** to open a file picker. Supported file formats: | Format | Extension | Notes | |---|---|---| | CSV | `.csv` | Any column layout; auto-detects email addresses | | Excel (modern) | `.xlsx` | Reads all sheets; no header row required | | Excel (legacy) | `.xls` | Same as .xlsx | | Plain text | `.txt` | One email per line or delimited | | Tab-separated | `.tsv` | Auto-detected email column | CalGrid automatically scans **all columns and rows** in the file — no specific column layout is required. It extracts every valid email address it finds. **Import behavior:** - Newly imported emails are **merged** into the existing list (not replaced). - Duplicate emails are not automatically removed — use **✂ Remove Duplicates** after import if needed. - The import runs in the background — the UI remains responsive during large file imports. --- ### Method 3 — Drag and Drop Drag a supported file (`.csv`, `.xlsx`, `.xls`, `.txt`, `.tsv`) directly onto the recipient text area. CalGrid automatically imports all email addresses from the file. --- ## Removing Duplicates Click **✂ Remove Duplicates** to deduplicate the current recipient list. - Deduplication is **case-insensitive** (`John@Example.com` and `john@example.com` are treated as the same address). - The **order** of addresses is preserved — only the second (and subsequent) occurrences of a duplicate are removed. - A toast notification appears showing how many duplicates were removed and how many unique addresses remain. --- ## Recipient Counter The small counter label at the top-right of the Receivers panel shows the current number of valid recipient emails detected in the text area. --- ## Field Lock During Dispatch The recipient text area and the Upload/Deduplicate buttons are **locked** while a campaign is running. You cannot modify the recipient list during an active job. --- ## Privacy and Data Handling - Recipient email addresses are stored locally in encrypted form (`%LOCALAPPDATA%\CalGrid\workspaces.json`) using Windows DPAPI. - Recipient data is tied to your Windows user account. - A SQLite job ledger stores recipient **hashes** (not raw addresses) to prevent duplicate sends after crashes or restarts. - CalGrid never sends recipient email addresses to any external server other than Google Calendar API. --- ## Related Pages - [Template Tags](template-tags.md) - [Bulk Import Workflow](../workflows/bulk-import.md) - [Dispatch Controls](dispatch-controls.md) # Dispatch Controls The dispatch controls — **Start**, **Pause**, **Resume**, and **Stop** — manage the execution of your calendar campaign. --- ## The Four Controls | Button | Label | Action | |---|---|---| | ▶ | **Start** | Begin dispatching invitations to all recipients | | ❚❚ | **Pause** | Pause after the current batch completes | | ▶ | **Resume** | Continue from where the job was paused | | ■ | **Stop** | Cancel remaining recipients (cannot undo) | --- ## Start **When to use:** After you have configured your event details, recipients, and Google account. **What happens:** 1. CalGrid validates the event name, date/time, and recipient list. 2. If attachments are configured, CalGrid uploads them to Google Drive first. 3. CalGrid begins creating Google Calendar events in batches. 4. The Progress panel updates in real time. 5. The Start button becomes disabled; Pause and Stop become active. **Requirements before starting:** - Google account must be connected (🔓 Disconnect shown in sidebar) - Event name must not be empty - Date must be in the future - At least one valid recipient email must be present - A valid license session must be active --- ## Pause **When to use:** To temporarily halt dispatch without losing progress. **What happens:** 1. CalGrid finishes the current in-flight batch of requests (already sent to Google). 2. No new batches are started after the current one completes. 3. The status bar shows **Paused** in amber. 4. The Pause button is replaced by Resume and Stop. > **Important:** Pausing does not cancel requests that have already been sent to Google. Those invitations may still be created even after you click Pause. --- ## Resume **When to use:** After pausing, to continue sending to remaining recipients. **What happens:** 1. CalGrid picks up from where it left off. 2. Recipients who already received invitations are not contacted again. 3. The job continues until all recipients are processed or you Stop. --- ## Stop **When to use:** To permanently end the campaign before all recipients are processed. **What happens:** 1. CalGrid stops scheduling any new batches. 2. Any batch **already sent** to Google cannot be recalled — those invitations may still be created. 3. The Progress panel shows final Total / Done / Fail counts. 4. All controls return to their initial state. > **Warning:** Stop is not the same as deleting sent invitations. Google Calendar events that were already created will remain on recipients' calendars. CalGrid has no ability to delete or recall sent invitations. --- ## Button States | State | Available Buttons | |---|---| | Idle (no job) | **▶ Start** only | | Running | **❚❚ Pause**, **■ Stop** | | Paused | **▶ Resume**, **■ Stop** | | Completed | **▶ Start** (to send a new campaign) | --- ## Dispatch Mode Effect The [Dispatch Mode](dispatch-modes.md) (Safe / Normal / Fast / Ultra) affects how many invitations are sent per batch and the pacing between batches. You should select your dispatch mode **before** clicking Start, as it cannot be changed during an active job. --- ## Related Pages - [Progress Monitoring](progress-monitoring.md) - [Dispatch Modes](dispatch-modes.md) - [Troubleshooting](../help/troubleshooting.md) # Progress Monitoring The **Progress** panel (bottom-right of each workspace) shows real-time statistics for the active dispatch job. --- ## Progress Panel Elements ### Percentage and Count - **Large percentage number** — overall completion (e.g., `72%`) - **X/Y counter** — recipients processed / total recipients (e.g., `72/100`) ### Progress Bar A 6px horizontal bar that fills from left to right as the job advances. ### Stat Cards Four counters below the progress bar: | Card | Color | Meaning | |---|---|---| | **Total** | Neutral | Total number of recipients in this campaign | | **Done** | Green | Recipients who received a successful calendar event | | **Fail** | Red | Recipients where the Google API returned an error | | **Left** | Neutral | Recipients remaining to be processed | --- ## Status Badge The small badge in the top-right corner of the Progress panel header shows the current state: | Badge Text | Meaning | |---|---| | *(empty)* | Idle | | **Working** | Job is running | | **Paused** | Job is paused | | **Done** | Job completed successfully | | **Stopped** | Job was stopped manually | --- ## Bottom Status Bar The bottom status bar (across the full width of the window) also shows dispatch state: | Indicator | Meaning | |---|---| | **● Ready** (grey) | No active job | | **● Working** (green) | Dispatching | | **● Paused** (amber) | Job is paused | | **● Error** (red) | An error occurred | --- ## Understanding "Done" vs. Invitation Delivery **Done** means Google Calendar API **acknowledged** the event creation request. It does **not** guarantee: - That the recipient opened or accepted the invitation - That the invitation email was delivered to the recipient's inbox - That the event appears in the recipient's calendar immediately Google Calendar invitation delivery depends on Gmail delivery, the recipient's calendar settings, and anti-spam filters — none of which CalGrid controls. --- ## Fail Count and Retries A **Fail** is counted when Google Calendar API returns an error for a recipient after all retry attempts are exhausted. Common causes of fails: - Temporary Google API quota limits (HTTP 429) - Network timeouts - Invalid recipient email address rejected by Google Calendar CalGrid automatically retries temporary errors using exponential backoff. The number of retry attempts is configured in [Settings → Rate](../settings/application-settings.md#rate-settings). --- ## Logs The live log view (accessible via **⚡ Debug** in the bottom bar) shows detailed per-recipient results and API error details. See [Debug Dialog](debug-dialog.md) for instructions. --- ## Desktop Notifications When a campaign finishes, CalGrid can show a **Windows desktop notification**. Enable or disable this in [Settings → App](../settings/application-settings.md#app-settings). --- ## Related Pages - [Dispatch Controls](dispatch-controls.md) - [Debug Dialog](debug-dialog.md) - [Settings Reference](../settings/application-settings.md) # Dispatch Modes CalGrid offers four **Dispatch Modes** that control the pacing, batch size, and anti-spam behavior of your campaigns. Each mode is a preset that balances deliverability against throughput. --- ## Selecting a Mode The mode selector appears in the **Title Bar**, centered at the top of the window: ``` [🛡️ Safe] [⚡ Normal] [🚀 Fast] [⚡⚡ Ultra] ``` Click any mode button to activate it. The currently active mode is highlighted with a colored border. The active mode is also shown in the **bottom status bar** (e.g., "⚡ Normal Mode"). > **Important:** The dispatch mode cannot be changed while a campaign is running. Select your mode before clicking Start. --- ## Mode Comparison | Mode | Invites per Batch | Rate Limit | Human Jitter | Slot Stagger | Best For | |---|---|---|---|---|---| | 🛡️ **Safe** | 1 | 1 req/s | 2–5 s | +15 min | Cold outreach, fresh accounts, maximum deliverability | | ⚡ **Normal** | 3 | 3 req/s | 1–2.5 s | +10 min | Balanced daily outreach for warmed accounts | | 🚀 **Fast** | 5 | 5 req/s | None | None | Bulk dispatch for established warm domains | | ⚡⚡ **Ultra** | 10 | 10 req/s | None | None | Internal team sync, pipeline testing | --- ## Mode Descriptions ### 🛡️ Safe Mode **Recommended for:** Cold outreach, fresh Google accounts, campaigns where inbox placement is critical. Safe Mode sends one invitation per request with significant delays between requests and a 15-minute time stagger between recipients. This closely mimics human scheduling behavior and maximizes the chance that invitations land in recipients' primary inboxes. Settings applied: - Batch size: 1 - Rate: 1 request/second - Human jitter: 2.0–5.0 seconds - Slot stagger: +15 minutes per recipient - Invisible entropy: enabled --- ### ⚡ Normal Mode **Recommended for:** Most regular outreach campaigns. Normal Mode is the default. It sends 3 invitations per batch at 3 requests/second with moderate jitter and a 10-minute stagger. It balances deliverability with reasonable throughput. Settings applied: - Batch size: 3 - Rate: 3 requests/second - Human jitter: 1.0–2.5 seconds - Slot stagger: +10 minutes per recipient - Invisible entropy: enabled --- ### 🚀 Fast Mode **Recommended for:** Bulk dispatch to warm, known-good recipient lists where speed matters. Fast Mode sends 5 invitations per batch with no jitter or stagger. It is significantly faster than Normal but provides less deliverability protection for cold contacts. Settings applied: - Batch size: 5 - Rate: 5 requests/second - Human jitter: disabled - Slot stagger: disabled - Invisible entropy: enabled --- ### ⚡⚡ Ultra Mode **Recommended for:** Internal team notifications, development/testing, or non-external calendars. Ultra Mode maximizes throughput at 10 invitations per batch. It is not recommended for external outreach or inbox deliverability goals. Settings applied: - Batch size: 10 - Rate: 10 requests/second - Human jitter: disabled - Slot stagger: disabled - Invisible entropy: disabled --- ## Mode vs. Manual Settings Selecting a mode applies a **preset** of settings. You can further customize individual settings in [Settings → Calendar, Rate, and Advance](../settings/application-settings.md) for fine-grained control. > **Note:** Switching modes while settings are open will update the displayed values to match the selected mode's preset. --- ## Related Pages - [Settings Reference — Rate & Advance](../settings/application-settings.md) - [Dispatch Controls](dispatch-controls.md) - [Sending Your First Campaign](../workflows/sending-first-campaign.md) # Brand Identity The **Brand Identity** feature lets you customize how your organization appears on calendar invitations by displaying a brand name and routing events through a specific calendar. --- ## Overview When Brand Identity is enabled, CalGrid: - Formats event titles as `[Brand Name] Event Title` - Adds `Organizer: Brand Name` to the event description - Optionally routes events to a specific Google Calendar (instead of the default primary calendar) --- ## Accessing Brand Settings 1. In the left sidebar, find the **Advance** section. 2. Click **🏷️ Brand Name**. 3. The Brand Calendar Settings dialog opens. --- ## Brand Calendar Settings Dialog | Field | Description | |---|---| | **Brand Name** | Your organization or brand name (e.g., "Acme Corporation") | | **Brand Calendar ID (optional)** | A specific Google Calendar ID to send events to (leave blank to use workspace default) | | **Save as default** | Apply this brand to all new workspaces automatically | ### Buttons | Button | Action | |---|---| | **Save** | Apply brand settings to this workspace | | **Cancel** | Discard changes | | **Turn Off Brand** | Clear brand settings and return to standard scheduling | --- ## Enabling Brand Identity 1. Click **🏷️ Brand Name** in the sidebar. 2. Enter your **Brand Name** (required). 3. Optionally enter a **Brand Calendar ID** (use the email-style calendar ID from Google Calendar settings, e.g., `c_xxx@group.calendar.google.com`). 4. Check **Save as default** if you want this brand to apply automatically to all future workspaces. 5. Click **Save**. After saving: - The sidebar shows an active brand indicator: `● Your Brand Name` - Event titles are automatically formatted as `[Your Brand Name] Your Event Title` - The brand name is added to the event description as "Organizer: Your Brand Name" --- ## Using a Specific Brand Calendar If you specify a **Brand Calendar ID**, CalGrid routes all events for this workspace to that calendar instead of the recipient's primary calendar. To find your Brand Calendar ID: 1. Open Google Calendar. 2. Click the three dots next to the calendar you want to use. 3. Select **Settings and sharing**. 4. Scroll down to find the **Calendar ID** (looks like `c_xxx...@group.calendar.google.com`). --- ## Disabling Brand Identity 1. Click **🏷️ Brand Name** in the sidebar. 2. Click **Turn Off Brand**. 3. Brand settings are cleared for this workspace. 4. Future events from this workspace will not include brand formatting. --- ## Brand vs. Settings Calendar ID CalGrid distinguishes between two calendar routing options: - **Settings → Calendar ID** — the global default calendar used when no brand is configured - **Brand Calendar ID** — overrides the settings calendar ID when brand is active Disabling the brand reverts to the Settings calendar ID. The brand calendar ID is never stored in Settings unless you check **Save as default**. --- ## Related Pages - [Interface Overview](interface-overview.md) - [Settings Reference](../settings/application-settings.md) - [Event Details](event-details.md) # Event Attachments CalGrid can attach files to calendar invitations using **Google Drive**. Each recipient's invitation includes a link to the shared file. --- ## Overview When you attach a file, CalGrid: 1. Uploads the file to Google Drive (before the campaign starts) 2. Shares the file individually with each recipient (reader access only, by name — not "anyone with link") 3. Attaches the Drive file link to each calendar event --- ## Requirements - Google Drive API must be enabled in your Google Cloud project - Your connected Google account must have Drive access If the Drive API is not enabled, CalGrid automatically shows a **Drive Guide** dialog with step-by-step instructions to enable it. --- ## Attaching a File 1. In the left sidebar, find the **Advance** section. 2. Click **📎 Event Attachment**. 3. A file picker opens — select one or more files to attach. 4. Each selected file appears as a badge card in the sidebar showing the filename. **Supported file types:** Any file type that Google Drive accepts (PDF, images, documents, spreadsheets, etc.) --- ## Managing Attachments ### Adding Multiple Files Click **📎 Event Attachment** again to add more files. Each file is added as a separate attachment. If a file with the same name is already attached, it is silently skipped. ### Removing an Attachment Each attachment badge in the sidebar has an **✕** button on the right. Click it to remove that specific file. ### Configuring Attachment Settings & Delivery Rules Click the small **⚙** (gear) button next to the attachment button to open the **Attachment Settings & Delivery Rules Hub** (`AttachmentNameDialog`). This modernized, modular hub (580×520 px) hosts two core cards: #### 1. Dynamic Filename Templating Personalize how attached files are named on the calendar event for each recipient using dynamic template tags: - **Single-Line Layout**: Features a streamlined horizontal input with a direct `[ ✦ Insert tags · 21 ▾ ]` picker button and an inline `👁️ Preview:` badge. - **Supported Tags**: You can include placeholders such as `{name}`, `{email}`, `{brand}`, `{id}`, `{ref}`, `{date}`, or `{time}` in the attachment title template. - **Example Template**: `{name} - Confidential Agreement - {date}.pdf` - **Output**: Each recipient sees an attachment personalized to them (e.g., `John - Confidential Agreement - 2026-12-15.pdf`). The original file extension is always safely preserved. #### 2. 🛡️ Ghost Attachment Anti-Spam Shield CalGrid features an enterprise-grade deliverability shield to prevent Google Mail & Calendar spam filters from fingerprinting high-volume attachments: - **Enable Ghost Shield**: Master toggle to activate attachment fingerprint obfuscation. - **Drive Ghost Copies (Pool Size 1–5)**: Uploads multiple independent copies of the attachment to Google Drive. The dispatch engine rotates these links round-robin across recipients so that no single Drive file URL is flooded. - **Polymorphic Hash Mutation**: Morphs the binary SHA-256 hash of each uploaded copy (via format-safe non-destructive comment injection for PDF, JPEG, and PNG) so each copy has a completely unique cryptographic fingerprint while rendering identically. - **Zero-Width Invisible Title Entropy**: Injects invisible Unicode entropy characters into calendar attachment titles to defeat regex-based spam filters. - **Isolated Recipient Sharing**: Each ghost Drive file copy is shared strictly with its assigned slice of recipients (`type=user, role=reader`), preserving privacy and security. --- ## Attachment Upload Process When you click **▶ Start**, CalGrid: 1. Uploads all attached files to Google Drive sequentially (before any calendar events are created) 2. Verifies the upload succeeded 3. Shares each file with each recipient by email (reader-only permission) 4. Proceeds to create calendar events with the attachment links included > **Note:** If any attachment upload fails, the campaign does not start. Fix the Drive configuration and retry. --- ## Drive Permission Policy CalGrid shares each Drive file **only with named recipients** (by email, reader-only). It does **not** create "anyone with the link" sharing. This means: - Only recipients in your list can access the attached files - Sharing uses `type=user, role=reader` for each recipient --- ## Drive Guide Dialog If the Google Drive API is not enabled, CalGrid automatically shows the **Drive Guide** dialog with five steps: 1. Enable Drive API in Google Cloud Console 2. Verify your OAuth client has Drive scope 3. Reconnect your Google account in CalGrid 4. Test an attachment Click the step buttons in the dialog to open the relevant Google Cloud Console pages. --- ## Related Pages - [Google API Setup](../getting-started/google-api-setup.md) - [Google Auth](google-auth.md) - [Troubleshooting — Attachments](../help/troubleshooting.md#attachment-issues) # Template Tags CalGrid supports **dynamic template tags** that personalize each invitation with recipient-specific data. Use tags in the event name, message description, and other text fields. --- ## Overview Template tags are placeholders written as `{tag_name}` that CalGrid replaces with real values for each recipient when creating events. For example, if a recipient's email is `john.doe@company.com`, the tag `{name}` becomes `John Doe`. --- ## Available Tags ### Recipient Identity Tags | Tag | Example Output | Description | |---|---|---| | `{name}` | `John` | Recipient's capitalized first name derived from email prefix | | `{username}` | `john.doe` | Email username portion before the `@` symbol | | `{email}` | `john.doe@example.com` | Full recipient email address | | `{domain}` | `example.com` | Recipient's email domain host | | `{company}` | `Example` | Capitalized company name extracted from domain | ### Schedule & Calendar Tags | Tag | Example Output | Description | |---|---|---| | `{date}` | `2026-12-15` | Scheduled event date (YYYY-MM-DD; reflects slot stagger) | | `{time}` | `10:00 AM` | Scheduled start time in 12-hour format (reflects slot stagger) | | `{day}` | `Wednesday` | Scheduled day of the week | | `{duration}` | `30 mins` | Scheduled event duration | ### Anti-Spam & Reference Tags | Tag | Example Output | Description | |---|---|---| | `{id}` | `A7B2X9` | Deterministic 6-char alphanumeric code unique to this recipient | | `{ref}` | `REF-A7B2X9` | Formatted tracking reference token | | `{random}` | `48291` | Unique 5-digit random number per invite | | `{spin:A\|B\|C}` | `A` or `B` or `C` | Spintax rotator (deterministic selection per recipient) | ### Brand & Sender Tags | Tag | Example Output | Description | |---|---|---| | `{brand}` | `Acme Corp` | Active brand identity name configured in workspace | | `{sender}` | `outreach@company.com` | Connected Google sender account email | --- ## Using Tags in Fields Tags work in: - **Event name (title)** - **Message (description)** - **Meeting Link / Location** (plain text portions) ### Example — Personalized Message ``` Hi {name}, You are invited to our {spin:annual|quarterly|monthly} review meeting with {brand}. Your appointment is scheduled for {day}, {date} at {time} ({duration}). Tracking Ref: {ref} ``` Each recipient receives a unique version: - `john.doe@acme.com` might get: "Hi John, You are invited to our annual review meeting with Acme... scheduled for Wednesday, 2026-12-15 at 10:00 AM (30 mins). Tracking Ref: REF-A7B2X9" - `sarah.connor@tech.org` might get: "Hi Sarah, You are invited to our quarterly review meeting with Acme... scheduled for Wednesday, 2026-12-15 at 10:15 AM (30 mins). Tracking Ref: REF-C4F1E8" --- ## Spintax Spintax allows you to rotate through multiple versions of text for each recipient: ``` {spin:Good morning|Hello|Hi there} ``` CalGrid selects one option per recipient based on a deterministic algorithm — the same recipient always gets the same option for the same campaign. This ensures consistency without being completely random. You can nest spintax and combine it with identity tags: ``` {spin:Dear {name}|Hi {name}|Hello {name}} ``` --- ## Opening the Tags Reference Access the complete interactive tags reference by: - Clicking **Template tags** (link above the message editor in the Event Details panel) - Clicking **🏷 Tags** in the bottom status bar The Tags dialog shows all available tags with examples and allows 1-click copy to clipboard. ### Tags Dialog Controls | Element | Function | |---|---| | Search box | Filter tags by name or description | | Category pills | Filter by category (All, Identity, Date, Spintax, etc.) | | Tag pill (click) | Copy the tag to clipboard | | **Done** button | Close the dialog | --- ## Live Preview Click **👁 Live Preview** (above the message editor) to see how the message will look for a sample recipient with all tags filled in. This helps verify your template before sending. --- ## Related Pages - [Event Details](event-details.md) - [Personalized Invites Workflow](../workflows/personalized-invites.md) - [Settings — Advance (Slot Stagger)](../settings/application-settings.md#advance-settings) # Bottom Status Bar The thin dark bar at the very bottom of the CalGrid window provides quick access to tools, diagnostics, documentation, and application information. --- ## Bar Layout ``` [🏷 Tags] | ● Ready | ⚡ Normal Mode [⚡ Debug] [📄 Docs] [❓ Help] [🐛 Report] [ℹ️ About] | v1.0.2 ``` --- ## Left Side ### 🏷 Tags Opens the **Template Tags** dialog — an interactive reference showing all available dynamic placeholders. Use this when composing your invitation message to quickly look up and copy tags like `{name}`, `{email}`, `{spin:...}`. See [Template Tags](template-tags.md) for details. --- ### ● Status Indicator Shows the current dispatch state of the active workspace: | Indicator | Color | Meaning | |---|---|---| | ● Ready | Grey/White | Idle — no active job | | ● Working | Green | Campaign is dispatching | | ● Paused | Amber | Campaign is paused | | ● Error | Red | An error occurred | --- ### Mode Badge Shows the currently active dispatch mode (e.g., "⚡ Normal Mode"). The badge color corresponds to the mode: | Badge | Mode | |---|---| | 🛡️ Safe Mode (green) | Safe | | ⚡ Normal Mode (indigo) | Normal | | 🚀 Fast Mode (blue) | Fast | | ⚡⚡ Ultra Mode (amber) | Ultra | --- ## Right Side ### ⚡ Debug Opens the **Debug Diagnostics** dialog — a live log viewer showing API calls, errors, rate limit events, and worker status. Useful for troubleshooting failed invitations or understanding why the campaign is running slower than expected. See [Debug Dialog](debug-dialog.md) for details. --- ### 📄 Docs Opens documentation in the built-in browser panel (VS Code-style side panel). The documentation page loads within CalGrid — no external browser is required. --- ### ❓ Help Opens help resources in the built-in browser. --- ### 🐛 Report Opens the issue/bug reporting page in the built-in browser. --- ### ℹ️ About Opens the **About CalGrid** dialog, which shows: - Application version - Application description - Author information - System and runtime details (Python version, OS version) - Full keyboard shortcuts reference --- ### Version Label Shows the current CalGrid version (e.g., `v1.0.2`). --- ## Related Pages - [Template Tags](template-tags.md) - [Debug Dialog](debug-dialog.md) - [Dispatch Modes](dispatch-modes.md) # Debug Dialog The **Debug Dialog** provides real-time diagnostics for the CalGrid dispatch engine — API events, rate limit notifications, errors, and worker status. --- ## Opening the Debug Dialog Click **⚡ Debug** in the bottom status bar. --- ## Dialog Layout ### Header KPI Cards Four status cards at the top of the dialog: | Card | Shows | |---|---| | **WORKSPACE** | Active workspace name and tab ID | | **AUTH STATUS** | Google account connection state | | **WORKERS** | Number of active background worker threads | | **TOTAL EVENTS** | Total events created across all workspaces | --- ### Log Search and Filter A search bar and filter pills to narrow the log view: | Element | Function | |---|---| | Search field | Filter log entries by text content | | **All** pill | Show all log entries | | **Error** pill | Show only error entries (red) | | **Success** pill | Show only successful entries (green) | | **Info** pill | Show informational entries (grey/white) | --- ### Log Console A dark terminal-style log viewer showing timestamped entries: - **Green entries** — successful API calls, events created - **Red entries** — errors, quota exceeded, failed recipients - **Grey/white entries** — informational messages, rate limit events, batch status The log retains entries up to the **Log Retention Limit** configured in [Settings → App](../settings/application-settings.md#app-settings). --- ### Footer Actions | Button | Action | |---|---| | **Copy Report** | Generates a sanitized diagnostic report and copies it to clipboard | | **Clear** | Clears the log display (does not affect saved logs) | | **×** | Close the dialog | --- ## Understanding Log Entries ### Common Log Patterns | Entry | Meaning | |---|---| | `✓ event created: recipient@email.com` | Successfully created a calendar event | | `✗ failed: recipient@email.com — HTTP 429` | Rate limit hit; will retry | | `↺ Retry 2/5 — waiting 3.2s` | Backoff retry in progress | | `❚❚ Paused — waiting for resume` | Job is paused | | `📅 Slot staggering active: +15m interval` | Slot stagger is applied | | `🛡️ Unique Entropy active` | Invisible entropy injection is on | | `⏱️ Jitter 1.5s–4.5s` | Human jitter delay information | --- ## In-App Offline Test Runner **⚡ Debug → Offline Tests** opens the separate **Offline Test Runner** window, which runs CalGrid's internal test suite without making any live Google API calls. See [Offline Test Runner](offline-test-runner.md) for details. --- ## Related Pages - [Progress Monitoring](progress-monitoring.md) - [Offline Test Runner](offline-test-runner.md) - [Troubleshooting](../help/troubleshooting.md) # Offline Test Runner CalGrid includes a built-in **Offline Test Runner** that validates the application's internal logic without making any live Google API calls. --- ## Purpose The Offline Test Runner is a diagnostic tool for verifying that CalGrid's core engine is working correctly on your Windows PC. It is primarily useful for: - Verifying that the installation is correct after setup - Diagnosing environment-specific issues - Running regression checks after system changes > **Note:** The Offline Test Runner does not send any real invitations. All tests use mock data and simulated API responses. --- ## Accessing the Test Runner 1. Click **⚡ Debug** in the bottom status bar. 2. In the Debug dialog, click **Offline Tests**. A separate window opens with the test runner interface. --- ## Test Runner Options | Option | Description | |---|---| | **Offline Checks** | Runs Phase-01 through Phase-04 mocks and Windows UI checks (the standard quick check) | | **Full Regression** | Runs the complete test suite including tests with known legacy failures | --- ## Running Tests 1. Select **Offline Checks** or **Full Regression**. 2. Click **Run Tests**. 3. The output panel shows test results as they execute. 4. Summary counters show Pass / Fail / Error counts. 5. When complete, the subprocess exit status is displayed. ### Controls During Test Run | Button | Action | |---|---| | **Stop** | Terminate the running test process | | **Copy Summary** | Copy the test result summary to clipboard | --- ## Test Result Storage The last sanitized test result is saved to `notes/offline_test_last_result.json` (a Git-ignored local file) for reference. This file is for local review only and does not leave your machine. --- ## Interpreting Results - A result of **20/20 pass** (Offline Checks) indicates the core engine is healthy. - Failures in the Full Regression suite may include pre-existing legacy test contract issues that do not affect actual application functionality. - Production readiness assessment requires live Google API testing with a consented test account — the Offline Test Runner alone does not certify the application for production use. --- ## Related Pages - [Debug Dialog](debug-dialog.md) - [Troubleshooting](../help/troubleshooting.md) # Workflows Step-by-step guides for the most common CalGrid tasks. --- ## Available Workflows | Workflow | Description | |---|---| | [Sending Your First Campaign](sending-first-campaign.md) | Complete walkthrough from setup to dispatch | | [Bulk Recipient Import](bulk-import.md) | Importing large lists from CSV or Excel files | | [Running Parallel Campaigns](multi-workspace.md) | Operating multiple workspaces simultaneously | | [Personalized Invites](personalized-invites.md) | Using tags and spintax for per-recipient messages | # Sending Your First Campaign This guide walks through the complete process of setting up and sending a batch of Google Calendar invitations with CalGrid. --- ## Prerequisites Before starting, ensure you have: - [ ] CalGrid installed and license activated - [ ] A Google Cloud project with Calendar API enabled - [ ] An OAuth Desktop client JSON file downloaded - [ ] A list of recipient email addresses If any of these are missing, start with [Getting Started](../getting-started/index.md). --- ## Step 1 — Connect Your Google Account 1. Open CalGrid. 2. In the left sidebar, under **Google Auth**, click **+ Add**. 3. Select your OAuth client JSON file. 4. Click **🔗 Connect**. 5. Complete Google authorization in your browser. 6. Return to CalGrid — the sidebar shows **🔓 Disconnect** and your email appears in the title bar. **Expected result:** Green dot + account email in the title bar. --- ## Step 2 — Configure Your Event In the **📅 Event Details** panel (left side of the workspace): 1. **Name:** Type your event title (e.g., "Team Strategy Meeting"). 2. **Date & Time:** Click the date field, open the calendar picker, and select a future date and time. 3. **Meeting Link / Location:** (Optional) Paste a Google Meet URL or venue address. 4. **Message:** Write your invitation message in the description area. > **Tip:** Use `{name}` in your message to personalize it with each recipient's name automatically. --- ## Step 3 — Add Recipients In the **📧 Receivers** panel (top-right): **Option A — Paste directly:** Click the email text area and paste your email list (one per line, or comma-separated). **Option B — Upload a file:** Click **📁 Upload List** and select a CSV, Excel, or text file containing email addresses. **Check the counter:** The hint at the top of the Receivers panel shows how many valid emails are detected. --- ## Step 4 — Choose a Dispatch Mode In the **Title Bar**, select your dispatch mode: | Use case | Recommended mode | |---|---| | Cold outreach / fresh account | 🛡️ Safe | | Standard daily outreach | ⚡ Normal | | Warm lists / bulk | 🚀 Fast | | Internal team only | ⚡⚡ Ultra | --- ## Step 5 — Start the Campaign Click **▶ Start** in the Receivers panel. CalGrid validates your configuration. If everything is correct, the job begins. You will see: - The Progress panel updating with percentage and counts - The status bar showing "● Working" in green - The Start button becoming disabled; Pause and Stop become active --- ## Step 6 — Monitor Progress Watch the **📊 Progress** panel: - **% bar** — visual completion - **Done** — events successfully created - **Fail** — events that encountered errors (retried automatically) - **Left** — remaining recipients For detailed logs, click **⚡ Debug** in the bottom bar. --- ## Step 7 — Campaign Completes When all recipients are processed: - The Progress panel shows 100% - The status bar returns to "● Ready" - A Windows desktop notification appears (if enabled in Settings) - Review Done / Fail counts A **Fail** count means CalGrid was unable to create events for those recipients after all retry attempts. Check the Debug log for specific error messages. --- ## What Recipients See Each recipient receives: - A Google Calendar event invitation email - The event appears in their Google Calendar (if they accept) - The event shows your event title, date/time, location, and your message > **Note:** "Done" in CalGrid means Google Calendar API accepted the event creation. It does not guarantee inbox delivery of the invitation email or that recipients accepted the event. --- ## Related Pages - [Dispatch Modes](../guides/dispatch-modes.md) - [Template Tags](../guides/template-tags.md) - [Troubleshooting](../help/troubleshooting.md) # Bulk Recipient Import This workflow explains how to import large lists of email addresses from files into CalGrid. --- ## Supported File Formats | Format | Extension | Notes | |---|---|---| | CSV | `.csv` | Any column layout; auto-detects emails in all cells | | Excel (modern) | `.xlsx` | All sheets scanned; no header required | | Excel (legacy) | `.xls` | Same as .xlsx | | Plain text | `.txt` | One email per line or delimited | | Tab-separated | `.tsv` | Auto-detected email column | --- ## Method 1 — Upload Button 1. In the **📧 Receivers** panel, click **📁 Upload List**. 2. A file picker opens — navigate to your file and click **Open**. 3. CalGrid scans the file in the background (the UI stays responsive). 4. A status message appears showing the import progress. 5. When complete, the imported emails are merged into the existing list. --- ## Method 2 — Drag and Drop 1. Open File Explorer and find your email list file. 2. Drag the file directly onto the **email text area** in the Receivers panel. 3. Drop it — CalGrid automatically detects the file and starts importing. --- ## Auto-Detection Logic CalGrid does not require a specific column layout or header row. It scans every cell in every row and column of the file and extracts any string that matches a valid email pattern: ``` example@domain.com user.name+tag@company.org ``` This means you can import files with: - Multiple columns (e.g., Name, Email, Company) - Mixed data types in the same column - No header row at all - Multiple sheets (Excel) --- ## After Import After import completes: 1. The imported emails appear in the text area, merged with any existing list. 2. Click **✂ Remove Duplicates** to deduplicate the combined list. 3. Check the recipient counter to verify the total count. --- ## Import Performance CalGrid's importer is benchmarked at approximately **15,000 emails per 0.5 seconds**. Even very large lists (tens of thousands of rows) complete quickly without freezing the UI. --- ## Preparing Your File For best results: - Use `.csv` or `.xlsx` format - Ensure the file contains valid email addresses - Do not use password-protected Excel files - Very large files (100,000+ rows) are supported but may take a few seconds --- ## Deduplication After importing, click **✂ Remove Duplicates** to: - Remove case-insensitive duplicate emails (`John@example.com` = `john@example.com`) - Preserve the original order of unique addresses - Display a toast notification with the count removed --- ## Related Pages - [Receivers Guide](../guides/receivers.md) - [Sending Your First Campaign](sending-first-campaign.md) # Running Parallel Campaigns CalGrid supports multiple independent workspace tabs running simultaneously. This lets you send different campaigns to different audiences at the same time. --- ## Use Cases - Running separate campaigns for different events at the same time - Using different Google accounts in parallel (one per workspace) - Sending different messages to different recipient segments simultaneously - Splitting a large list across multiple workspaces for faster dispatch --- ## Setting Up Multiple Workspaces ### Step 1 — Create Your Workspaces 1. Click **+** in the tab bar to create a new workspace, or press `Ctrl + T` *(note that About modal lists Ctrl+N, but active runtime shortcut is Ctrl+T)*. 2. Repeat to create as many workspaces as you need. 3. Each workspace starts empty with default settings. ### Step 2 — Configure Each Workspace Independently For each workspace tab: 1. **Rename the tab** — Click the Name field in the sidebar and give it a descriptive name (e.g., "Campaign A — Tech Companies"). 2. **Connect a Google account** — Each workspace can use a different Google account. Use **+ Add** and **🔗 Connect** in each tab's sidebar. 3. **Set event details** — Configure the event name, date/time, and message for each workspace. 4. **Add recipients** — Each workspace has its own independent recipient list. 5. **Choose dispatch mode** — The mode selector in the title bar applies to the active workspace's display, but each workspace retains its own mode setting at job start. ### Step 3 — Start Each Workspace Switch to each workspace tab and click **▶ Start**. Workspaces run in completely independent background threads. Starting or stopping one workspace does not affect others. --- ## Monitoring Multiple Workspaces ### Tab Status Badges Each tab in the tab bar shows: - A connection dot: **Green** (Google account authorized) or **Grey** (not connected) - A status badge: Amber `{percent}%` (running), Cyan `❚❚ {percent}%` (paused), Green `✓` (completed), Red `✗` (cancelled) ### Switching Between Workspaces Click any tab to switch to it. You can monitor progress, check logs, or pause/stop jobs in any workspace without interrupting others. --- ## Pausing and Stopping Individual Workspaces Each workspace's Pause and Stop controls only affect that workspace: - **Pause** in Workspace 2 does not affect Workspace 1 or Workspace 3 - **Stop** in one workspace lets others continue running - Each workspace maintains its own progress and log state --- ## Resource Considerations Each active workspace uses: - One background worker thread - Google Calendar API quota from the connected Google account - Network bandwidth for API calls Google Calendar API quota limits apply per Google account. Using different Google accounts in different workspaces gives each workspace its own independent quota. --- ## Recommended Approach For best results when running parallel campaigns: 1. Use a **different Google account** per workspace if possible. 2. Use **Normal** or **Safe** mode for external outreach. 3. Keep the total number of simultaneous active workspaces to what your Google API quota supports. --- ## Related Pages - [Workspace Tabs](../guides/workspace-tabs.md) - [Dispatch Modes](../guides/dispatch-modes.md) - [Google Auth](../guides/google-auth.md) # Personalized Invites This workflow shows how to create invitations that are uniquely personalized for each recipient using CalGrid's template tag and spintax engine. --- ## Overview Personalization helps your invitations feel individual rather than mass-sent. CalGrid supports: - **Name and email tags** — insert the recipient's name, first name, domain, etc. - **Date and time tags** — show each recipient their personal appointment time (useful with Slot Stagger) - **Spintax rotation** — vary the wording across recipients to avoid repetitive patterns --- ## Step 1 — Write Your Message with Tags In the **Message (Description)** field of the Event Details panel, write your invitation using tags: ``` Dear {name}, We'd like to invite you to {spin:our upcoming webinar|our online session|a live demo} on {date} at {time}. The session is designed for {domain} professionals like yourself. Looking forward to seeing you, The Events Team ``` Each recipient receives a unique version: - `John` at `acme.com` might get: "Dear John, We'd like to invite you to our upcoming webinar on 2026-12-15 at 10:00 AM. The session is designed for acme.com professionals..." - `Sarah` at `techcorp.com` might get: "Dear Sarah, We'd like to invite you to a live demo on 2026-12-15 at 10:15 AM. The session is designed for techcorp.com professionals..." --- ## Step 2 — Add Tags to the Event Title (Optional) You can also use tags in the event name: ``` {name}'s Strategy Call ``` This creates events titled "John's Strategy Call", "Sarah's Strategy Call", etc. --- ## Step 3 — Enable Slot Stagger for Appointment-Style Scheduling For appointment scheduling (each recipient at a different time): 1. Open **Settings** (`Ctrl + ,`). 2. Go to the **🛡️ Advance** category. 3. Enable **Time-Staggered Slot Booking**. 4. Set the **Slot Stagger Interval** (e.g., 15 minutes). 5. Click **Save Settings**. With stagger enabled: - Recipient 1 gets an event at your base time (e.g., 10:00 AM) - Recipient 2 gets an event at 10:15 AM - Recipient 3 gets an event at 10:30 AM - And so on... The `{time}` and `{date}` tags in your message automatically reflect each recipient's individual slot. --- ## Step 4 — Preview Your Message Click **👁 Live Preview** (above the message editor) to see how the message renders for a sample recipient. Verify that all tags are filled in correctly. --- ## Step 5 — Open the Tags Reference If you need to look up available tags: 1. Click **Template tags** (above the message editor), or 2. Click **🏷 Tags** in the bottom status bar. The Tags dialog shows all tags with examples and copy buttons. --- ## Step 6 — Send the Campaign Follow the standard [Sending Your First Campaign](sending-first-campaign.md) steps from Step 4 onward. --- ## Tips for Effective Personalization | Tip | Detail | |---|---| | Use `{name}` for natural greetings | `{name}` extracts the capitalized first name (e.g., `john.doe@...` becomes `John`) | | Test spintax with Live Preview | Verify all variants make grammatical sense | | Combine stagger + time tags | For appointment-style scheduling with personalized times | | Keep fallbacks in mind | If no name can be parsed from the email username, `{name}` safely falls back to `Friend` | --- ## Related Pages - [Template Tags](../guides/template-tags.md) - [Settings — Advance (Slot Stagger)](../settings/application-settings.md#advance-settings) - [Event Details](../guides/event-details.md) # Settings CalGrid's Settings dialog lets you configure every aspect of dispatch behavior, rate limiting, reminders, and application preferences. --- ## Opening Settings **Method 1:** Click the **⚙** button in the title bar. **Method 2:** Press `Ctrl + ,`. --- ## Settings Categories | Category | Contents | |---|---| | [📅 Calendar](application-settings.md#calendar-settings) | Calendar ID, batch size, duration, timezone, send updates | | [⏱️ Rate](application-settings.md#rate-settings) | API rate limit, retries, backoff delay, timeout | | [🔔 Invites](application-settings.md#invitations-settings) | Guest visibility, Meet links, reminders | | [🛡️ Advance](application-settings.md#advance-settings) | Jitter, slot stagger, multi-tier reminders, entropy injection | | [💻 App](application-settings.md#app-settings) | Log retention, auto-scroll, desktop notifications, sound alerts | --- ## Navigating Settings - **Search box** — type any keyword (e.g., "timezone", "batch", "jitter") to filter settings across all categories - **Category pills** — click a category button to show only that category's settings - **Ctrl+F** — focus the search box - **Escape** — clears the search box if focused; otherwise closes the dialog --- ## Saving and Resetting | Action | Button | Keyboard | |---|---|---| | Save changes | **Save Settings** | Enter | | Discard changes | **Cancel** | Escape | | Reset all to defaults | **↺ Reset Defaults** | — | Changes take effect immediately after saving. Cancelled changes are discarded. # Settings Reference Complete reference for all CalGrid settings. Open Settings with `Ctrl + ,` or the ⚙ button in the title bar. --- ## Calendar Settings {#calendar-settings} Settings in the **📅 Calendar** category control how events are created and dispatched. --- ### Default Calendar ID **Default:** `primary` The Google Calendar ID where events are created. Use `primary` to send to the recipient's primary calendar. Use a specific calendar email (e.g., `c_xxx@group.calendar.google.com`) to target a custom calendar. > **Note:** When Brand Calendar is active for a workspace, it overrides this setting for that workspace only. See [Brand Identity](../guides/brand-identity.md). --- ### Batch Size **Default:** 100 | **Range:** 1–100 Maximum number of calendar event creation requests bundled into a single Google Calendar HTTP batch request. Larger batches are more efficient but may hit quota limits faster. Effective batch size is `min(Batch Size, Rate Limit/second, 100)`. --- ### Default Event Duration **Default:** 30 min | **Range:** 5–480 min | **Step:** 5 min Duration in minutes for calendar events created by CalGrid. For example, a value of 30 creates events from the start time to 30 minutes later. --- ### Default Timezone **Default:** Local (Auto-detect) The timezone assigned to event start and end timestamps. Options include: | Option | Description | |---|---| | Local (Auto-detect) | Uses your Windows system timezone | | UTC | Coordinated Universal Time | | America/New_York | Eastern Time (US) | | America/Chicago | Central Time (US) | | America/Denver | Mountain Time (US) | | America/Los_Angeles | Pacific Time (US) | | Europe/London | GMT/BST | | Europe/Paris | CET/CEST | | Asia/Dubai | GST | | Asia/Dhaka | BST (Bangladesh) | | Asia/Kolkata | IST | | Asia/Singapore | SGT | | Asia/Tokyo | JST | | Australia/Sydney | AEST/AEDT | | *(and more)* | Additional IANA timezones | > **Note:** If you have a custom timezone saved that is not in the list, CalGrid appends it to the list automatically. --- ### Send Updates Mode **Default:** `all` Controls whether Google Calendar sends invitation emails to attendees. | Option | Behavior | |---|---| | `all` | Send invitation emails to all attendees (internal and external) | | `externalOnly` | Send only to attendees outside your Google Workspace domain | | `none` | Do not send any invitation emails (events are created silently) | --- ## Rate Settings {#rate-settings} Settings in the **⏱️ Rate** category control API pacing and error recovery. --- ### API Rate Limit **Default:** 5 req/s | **Range:** 1–50 req/s Maximum Google Calendar API requests per second. This is a CalGrid-side limiter — Google's own quota limits (typically 600 requests/minute per user) always apply independently. > **Tip:** Dispatch modes (Safe / Normal / Fast / Ultra) automatically configure this setting. Adjust manually only if you need fine-grained control beyond the preset modes. --- ### Max Retry Attempts **Default:** 5 | **Range:** 0–10 Number of automatic retry attempts when a request fails with a temporary error (HTTP 429 Too Many Requests or HTTP 503 Service Unavailable). Set to 0 to disable retries entirely. --- ### Base Backoff Delay **Default:** 1.5 s | **Range:** 0.5–10.0 s Starting delay multiplier for exponential backoff on retries. When a request fails, CalGrid waits `Base Backoff × 2^retry_number` seconds before retrying (with randomized jitter added). --- ### HTTP Request Timeout **Default:** 30 s | **Range:** 5–120 s | **Step:** 5 s Maximum time (in seconds) CalGrid waits for a Google Calendar API response before considering a request failed. --- ## Invitations Settings {#invitations-settings} Settings in the **🔔 Invites** category control privacy and notification behavior for created events. --- ### Guests Can See Other Guests **Default:** Off (unchecked) When enabled, attendees can see the full list of other invited guests in the event details. Keep disabled for privacy when sending to multiple unrelated recipients. --- ### Guests Can Invite Others **Default:** Off (unchecked) When enabled, invited guests can forward or share the invitation with additional people. Keep disabled to prevent unauthorized redistribution of the invitation. --- ### Default Reminder **Default:** 15 min | **Range:** 0–120 min Minutes before the event when Google Calendar sends the recipient a reminder popup. Set to 0 to disable reminders. > **Note:** This setting is automatically disabled when **Multi-Tier Reminders** (in Advance settings) is enabled, as the two systems conflict. --- ### Auto Generate Meet Link **Default:** Off (unchecked) When enabled, CalGrid instructs Google Calendar to automatically generate a unique Google Meet conference link for each created event. The meeting link appears in the event details for all attendees. Leave disabled if you are providing your own meeting URL in the **Meeting Link / Location** field. --- ## Advance Settings {#advance-settings} Settings in the **🛡️ Advance** category enable anti-spam and smart scheduling features. All Advance settings default to off. --- ### Randomized Human Jitter **Enable Human Jitter:** Off | **Min Delay:** 1.5 s | **Max Delay:** 4.5 s When enabled, CalGrid adds a randomized pause between each request dispatch. The pause is a random duration between Min Delay and Max Delay seconds. **Purpose:** Mimics human scheduling behavior to reduce the chance of Google anti-abuse detection flagging your account. > **Note:** Jitter is non-blocking — it responds instantly to Pause and Stop commands during the wait. The active workspace shows a meta label (e.g., `⏱️ Jitter 1.5s–4.5s`) when jitter is configured. --- ### Time-Staggered Slot Booking **Enable Slot Stagger:** Off | **Stagger Interval:** 15 min When enabled, each recipient's event start time is offset by the configured interval: - Recipient 1: Base time (e.g., 10:00 AM) - Recipient 2: Base + 15 min (10:15 AM) - Recipient 3: Base + 30 min (10:30 AM) - ... **Purpose:** Creates individual appointment slots instead of inviting everyone to the same time. Essential for scheduling one-on-one calls or appointments at scale. The `{time}`, `{date}`, and `{day}` template tags automatically reflect each recipient's individual staggered time. **Stagger interval range:** 5–240 minutes. --- ### Multi-Tier Reminder Notifications **Enable Multi-Tier Reminders:** Off When enabled, CalGrid sends up to three separate reminder notifications per event instead of a single reminder. | Tier | Default Minutes | Default Method | |---|---|---| | Tier 1 | 1440 (24 hours) | Email | | Tier 2 | 60 (1 hour) | Popup | | Tier 3 | 15 (15 minutes) | Popup | Each tier has a **minutes** spinbox and a **method** selector (Email or Popup). Set any tier to **0 (Off)** to disable that tier while keeping others active. **Deduplication:** CalGrid automatically removes duplicate (method, minutes) combinations before sending to the Google API, preventing HTTP 400 errors. > **Important:** Enabling Multi-Tier Reminders automatically disables the Default Reminder setting in the Invites category. --- ### Invisible Entropy Injection **Default:** Off When enabled, CalGrid appends a unique sequence of invisible zero-width Unicode characters to each invitation description. The characters are invisible to human readers but make each event's byte content unique. **Purpose:** Bypasses Gmail/Google Calendar repetitive template fingerprinting that may cause invitations to be treated as spam when hundreds of identical messages are detected. The workspace status shows `🛡️ Unique Entropy` when entropy is active. --- ## App Settings {#app-settings} Settings in the **💻 App** category control the application interface and notification behavior. --- ### Log Retention Limit **Default:** 2000 | **Range:** 100–10,000 Maximum number of log entries retained in the Debug dialog's log console. Older entries are removed when the limit is reached. Increase for long-running campaigns where you need longer history. --- ### Auto-Scroll Logs **Default:** On (checked) When enabled, the log console automatically scrolls to the newest entry as it arrives. Uncheck to freeze the scroll position and read older entries while a job is running. --- ### Desktop Notifications **Default:** On (checked) When enabled, CalGrid shows a Windows system notification when a campaign completes. The notification includes the final Done/Fail counts. --- ### Sound Alerts **Default:** Off (unchecked) When enabled, CalGrid plays a sound when a campaign finishes. The sound uses the Windows system notification sound. --- ## Related Pages - [Dispatch Modes](../guides/dispatch-modes.md) - [Template Tags — Stagger Tags](../guides/template-tags.md) - [Brand Identity](../guides/brand-identity.md) - [Troubleshooting](../help/troubleshooting.md) # Help & Support Resources for troubleshooting issues and getting answers. --- ## Available Help Resources | Resource | Description | |---|---| | [Troubleshooting](troubleshooting.md) | Solutions to common problems | | [FAQ](faq.md) | Frequently asked questions | | [Limitations](limitations.md) | Known limitations and boundaries | --- ## Quick Help Links - **License issues** → [Troubleshooting — License Issues](troubleshooting.md#license-issues) - **Google auth not working** → [Troubleshooting — Google Auth](troubleshooting.md#google-auth-issues) - **Invitations not delivered** → [Troubleshooting — Deliverability](troubleshooting.md#deliverability) - **Attachment errors** → [Troubleshooting — Attachments](troubleshooting.md#attachment-issues) - **Application not starting** → [Troubleshooting — Startup](troubleshooting.md#startup-issues) --- ## Reporting Issues Click **🐛 Report** in the bottom status bar to open the issue reporting page in the built-in browser. When reporting issues, include: - CalGrid version (shown in the About dialog or bottom bar) - Windows version - A description of what you expected vs. what happened - The error message (copy from the Debug dialog log) # Troubleshooting Solutions for common problems in CalGrid. --- ## License Issues {#license-issues} ### "Invalid license key. Please check and try again." **Cause:** The key was entered incorrectly, or the key is not registered. **Solutions:** - Use the **Show** button to reveal the key and verify there are no extra spaces - Copy-paste the key directly from the email or purchase confirmation - Contact your seller to verify the key is active --- ### "This license has expired. Please renew to continue." **Cause:** Your license subscription period has ended. **Solution:** Renew your license through your seller or distributor, then enter the new key. --- ### "Device limit reached for this license." **Cause:** The license key has been used on the maximum number of Windows PCs allowed. **Solution:** Contact your seller to remove old device bindings or upgrade your license. --- ### "Unable to verify. Check your connection and try again." **Cause:** CalGrid cannot reach the license verification server. **Solutions:** - Check that you have an active internet connection - Temporarily disable any firewall or VPN that may be blocking outbound HTTPS connections to `ivib.cc` - Try again after a few minutes --- ### CalGrid shows the license screen every time I start **Cause:** The license session could not be re-established, or the license service is unavailable. **Solutions:** - Verify your internet connection is active - Enter your license key again - Check if your license has expired --- ## Google Auth Issues {#google-auth-issues} ### "⏳ Verify..." stays indefinitely after restart **Cause:** The background credential verification is not completing. **Solutions:** - Wait up to 20 seconds — the check has a built-in timeout - If still stuck, click **🔗 Connect** to manually re-authorize --- ### Browser opens but nothing happens after Google sign-in **Cause:** The OAuth callback did not reach CalGrid's local listener. **Solutions:** - Ensure no other application is blocking `localhost` on the callback port - Try closing and reopening CalGrid, then clicking **🔗 Connect** again - Use a Desktop app OAuth client JSON (not Web application type) --- ### "✓ JSON" button shows but Connect button is disabled **Cause:** A dispatch job is active, preventing auth changes during operation. **Solution:** Stop the current job, then connect your Google account. --- ### After reconnecting, old workspace is still not connected **Cause:** The workspace state did not update correctly. **Solution:** Click **🔗 Connect** in the sidebar of the specific workspace that is not connected. --- ## Dispatch and Delivery Issues {#deliverability} ### Many recipients show as "Fail" **Causes and solutions:** | Cause | Solution | |---|---| | Google API quota exceeded | Switch to **Safe** or **Normal** mode; wait and retry later | | Invalid email addresses | Use **✂ Remove Duplicates** and manually check for malformed addresses | | Temporary Google service outage | Check [Google Workspace Status](https://www.google.com/appsstatus) and retry later | | Rate limit too high | Lower the API Rate Limit in Settings | --- ### Invitations are not arriving in recipients' inboxes **Important:** CalGrid creates Google Calendar events — it does not control Gmail delivery. **Possible reasons:** - Recipient's Gmail is filtering invitations from unknown senders - Recipient's Google Calendar settings reject automatic invitations - Google anti-spam filters detected repeated identical messages (use Invisible Entropy and Spintax) **What you can verify:** - Check the Debug log for HTTP 200 responses — this confirms Google accepted the event - Ask a test recipient to check their Spam folder and Google Calendar --- ### Campaign is running very slowly **Causes and solutions:** | Cause | Solution | |---|---| | Human Jitter is adding delays | Expected behavior in Safe/Normal mode; switch to Fast mode for speed | | Rate limit is set very low | Increase API Rate Limit in Settings | | Exponential backoff is active | Google is rate-limiting; reduce batch size and rate | --- ### "Start" button does nothing when clicked **Causes:** - Google account not connected — connect first - Event name is empty — add an event title - Date is in the past — set a future date/time - Recipient list is empty — add at least one email - License session is not active — verify your license --- ## Attachment Issues {#attachment-issues} ### "Drive Guide" dialog appears when attaching files **Cause:** Google Drive API is not enabled in your Google Cloud project. **Solution:** Follow the steps in the Drive Guide dialog to enable the Drive API and reconnect your account. --- ### Attachment upload fails at campaign start **Causes and solutions:** | Cause | Solution | |---|---| | Drive API not authorized | Reconnect your Google account after enabling Drive API | | File is too large | Reduce file size or compress before attaching | | File is locked by another application | Close the file in other programs before attaching | --- ## Startup Issues {#startup-issues} ### CalGrid doesn't start (double-clicking RUN_CalGrid.bat) **Solutions:** - Ensure Python 3.12 is installed and accessible as `py` - Verify that `pip install -r requirements.txt` completed without errors - Run from Command Prompt to see the error output: ``` .venv\Scripts\python.exe main.py ``` --- ### "PySide6 is required" error on startup **Solution:** Run: ```powershell .venv\Scripts\python.exe -m pip install -r requirements.txt ``` --- ### Application crashes immediately after license activation **Cause:** A missing dependency or incompatible Python version. **Solution:** - Verify Python 3.12 is installed: `py --version` - Reinstall dependencies: `.venv\Scripts\python.exe -m pip install -r requirements.txt` --- ## Data and Settings Issues ### My workspace data was lost after reinstalling Windows **Cause:** Workspace data is stored in `%LOCALAPPDATA%\CalGrid\` and is encrypted using Windows DPAPI (tied to your Windows user account). Data encrypted under a previous Windows installation cannot be decrypted on a new installation. **Prevention:** Back up `%LOCALAPPDATA%\CalGrid\` before reinstalling Windows. The backup is usable only on the same Windows user account. --- ### Settings I changed are not saving **Solutions:** - Ensure the `%LOCALAPPDATA%\CalGrid\` folder exists and is writable - Try running CalGrid as your normal user (not as Administrator) - Check available disk space --- ## Related Pages - [FAQ](faq.md) - [Limitations](limitations.md) - [Debug Dialog](../guides/debug-dialog.md) # Frequently Asked Questions --- ## General ### What is CalGrid? CalGrid is a Windows desktop application for scheduling and batch-sending Google Calendar invitations. It lets you send personalized calendar events to hundreds or thousands of recipients with features like anti-spam pacing, dynamic personalization, slot staggering, and Google Drive attachments. --- ### Does CalGrid work on Mac or Linux? No. CalGrid is a Windows-only application built with native Windows technologies (PySide6/Qt, Windows Credential Manager). No Mac or Linux version is available. --- ### Does CalGrid require a Google Workspace account? No. CalGrid works with standard personal Google accounts. You need a **Google Cloud project** with the Calendar API enabled and an OAuth Desktop client credential file, but no Workspace subscription is required. --- ### What does "Done" mean in the Progress panel? **Done** means the Google Calendar API successfully accepted the event creation request. It does **not** mean the recipient saw, accepted, or received an email about the invitation. Email delivery depends on Gmail's spam filters and the recipient's Google Calendar settings, which CalGrid cannot control. --- ## Google API & Authentication ### Can I use the same Google account in multiple workspaces? Yes. You can use the same OAuth JSON file and authorize the same Google account in multiple workspace tabs. However, all workspaces sharing an account also share that account's Google Calendar API quota. For best results with parallel campaigns, use different Google accounts in different workspaces. --- ### Do I need to re-authorize my Google account every time I restart CalGrid? No. CalGrid stores your OAuth token securely in Windows Credential Manager and restores your connection automatically on each launch. You only need to re-authorize if the token expires, is revoked, or you explicitly disconnect. --- ### My Google Cloud project is in "testing" mode. Will invitations be blocked? Invitations from an OAuth app in "testing" mode work normally — the limitation for testing-mode apps is the number of authorized test users (typically 100). Add your test recipients as test users in the Google Cloud Console OAuth consent screen. --- ### Why does the OAuth browser flow redirect to localhost? CalGrid uses Google's official "InstalledAppFlow" (Desktop app) OAuth flow, which uses a temporary local server on `localhost` to receive the authorization callback from Google. This is the standard, secure method for desktop app authentication. No server infrastructure is involved. --- ## Sending & Deliverability ### How many invitations can I send? Google Calendar API quota limits apply. The standard quota is typically 600 requests/minute per user, but this varies by Google Cloud project and account. CalGrid does not impose its own hard limit — configure your Batch Size and Rate Limit in Settings to stay within your quota. --- ### Can recipients opt out of receiving invitations? Google Calendar automatically handles invitation acceptance and decline for recipients. CalGrid cannot control or access recipients' responses. Recipients can delete unwanted events from their calendars directly. --- ### Can I send the same event to the same recipient twice? CalGrid uses a **SQLite job ledger** that stores recipient hashes (not raw addresses) and event IDs. If a campaign crashes or is restarted, CalGrid does **not** automatically re-send to recipients who already received an event in a previous run of the same campaign. This prevents unintentional duplicate invitations. --- ### Will recipients see each other's email addresses in the invitation? No. By default, **Guests Can See Other Guests** is disabled. Each recipient's event is created independently — recipients do not see the full list of other invited people. You can change this in [Settings → Invites](../settings/application-settings.md#invitations-settings). --- ## Attachments ### What file types can I attach? Any file type that Google Drive accepts can be attached. Common types include PDF, DOCX, XLSX, PPTX, PNG, JPG, and others. --- ### Where are attached files stored? Attached files are uploaded to your **Google Drive** account (the same account connected in the workspace). CalGrid uploads the file once and then shares it individually with each recipient by email. --- ### Is the attached file publicly accessible? No. CalGrid shares the file only with named recipients (by email address, reader-only permission). It does not create "anyone with the link" public access. --- ## Data & Privacy ### Where is my data stored? | Data | Location | |---|---| | Workspace data, recipient lists, logs | `%LOCALAPPDATA%\CalGrid\` (encrypted with Windows DPAPI) | | OAuth tokens | Windows Credential Manager | | Application settings | `%LOCALAPPDATA%\CalGrid\settings.json` | | Job ledger (recipient hashes, event IDs) | `%LOCALAPPDATA%\CalGrid\` (SQLite database) | --- ### Is my recipient list sent to CalGrid's servers? No. Recipient email addresses are only sent to the **Google Calendar API** to create events. They are never sent to CalGrid's licensing servers or any other service. --- ### Is my license key stored on disk? No. Your license key is verified in memory and immediately discarded after verification. It is never stored in any file on disk, in logs, or in the Windows registry. --- ## Related Pages - [Troubleshooting](troubleshooting.md) - [Limitations](limitations.md) - [Settings Reference](../settings/application-settings.md) # Known Limitations & Boundaries To ensure safe, predictable, and compliant operation, this document details the architectural boundaries, API constraints, and intentional limitations of CalGrid. --- ## 1. Google API & Invitation Lifecycle ### "Done" Status vs. Inbox Delivery - In CalGrid, an event marked **Done** indicates that Google Calendar API acknowledged event creation (`HTTP 200/201`). - CalGrid **cannot track or verify email delivery** to the recipient's inbox. Google Calendar and Gmail apply internal spam filtering, recipient notification preferences, and sender reputation checks independently. - Recipients who disable calendar notifications or whose mail providers flag external calendar invites may not receive an email alert. ### In-Flight Batches & Non-Retractable Requests - When you click **■ Stop** or **❚❚ Pause**, CalGrid terminates subsequent scheduling immediately. - However, any HTTP batch **already sent across the network** to Google cannot be recalled or aborted. Events within that in-flight batch may still be created on Google Calendar. - CalGrid does **not delete or recall** previously dispatched calendar events. Sent invitations remain on the creator's and recipients' calendars unless removed manually via Google Calendar. ### Google API Quota & Anti-Abuse Controls - Google enforces strict per-user and per-project quotas (typically 600 requests per minute per user, plus daily event creation and attendee limits). - Sending to too many external recipients too quickly from a new or un-warmed Google account can trigger temporary Google API throttling (`HTTP 429 Too Many Requests`) or account suspension. - CalGrid's cooperative rate limiter, human jitter, and exponential backoff mitigate quota issues, but cannot bypass Google's remote server policies. ### Service Account Restrictions - Standard Google Service Account credentials (`service_account` JSON) cannot send external calendar invitations without **Google Workspace Domain-Wide Delegation**. - For regular personal accounts (`@gmail.com`) or standard Google Workspace setups, always use an **OAuth 2.0 Desktop Client JSON** (`installed`). --- ## 2. Operating System & Platform ### Windows 64-Bit Only - CalGrid is compiled and verified strictly for **Windows 10 (64-bit)** and **Windows 11 (64-bit)**. - macOS, Linux, and 32-bit Windows architectures are unsupported. ### Single-User DPAPI Encryption - Workspace states, receiver lists, and execution logs are encrypted at rest using **Windows Data Protection API (DPAPI)**. - Encrypted data is cryptographically tied to the active Windows user account. - Transferring `%LOCALAPPDATA%\CalGrid` files to a different PC, another user profile on the same PC, or restoring files after a clean Windows reinstallation will render saved receiver lists and session logs unreadable. --- ## 3. Concurrency & Workspace Limits ### One Worker Per Workspace - Each workspace tab runs exactly one background daemon worker thread. Multiple workers cannot be attached to the same workspace tab simultaneously. - To dispatch across multiple accounts or queues in parallel, create separate workspace tabs. ### Memory & Log Retention - The live log viewer retains up to the configured limit (100 to 10,000 entries, default 2,000) to maintain low memory usage and high-density rendering speed. - Older entries are trimmed automatically from the live visual log. --- ## 4. Licensing & Network Connectivity ### Continuous License Verification - CalGrid requires an active internet connection on startup to verify license signatures with `https://ivib.cc`. - If the license server becomes temporarily unreachable while running, CalGrid provides a short offline grace period. Once the grace window lapses, dispatching is locked until connectivity is restored. - Hardware fingerprinting binds the license session to the active machine. Concurrent usage across multiple machines with a single-device license key is blocked. --- ## Related Pages - [Troubleshooting](troubleshooting.md) - [Frequently Asked Questions](faq.md) - [Dispatch Controls](../guides/dispatch-controls.md) - [Settings Reference](../settings/application-settings.md)