UTM Spreadsheet Requirements

Formatting rules for the tracking URL spreadsheet

Doing Good Digital — Last updated March 2026

Contents

  1. Preparing the Spreadsheet
  2. Spreadsheet Structure
  3. Required Columns
  4. Email Name Format
  5. Description Values
  6. Best Practices
Important The Email Builder relies on a correctly formatted UTM spreadsheet to insert tracking URLs into the generated emails. If the spreadsheet doesn’t follow these rules, URLs will be missing or mismatched.

1 Preparing the Spreadsheet

The PM or client typically provides a master UTM spreadsheet with many columns (Source Code, Sub Source, Fiscal Year, Month, Campaign, Channel, Effort, Segment, UTM_Source, UTM_Medium, UTM_Campaign, UTM_Content, etc.). The builder only needs three columns. Before uploading, trim the spreadsheet:

  1. Create a copy of the spreadsheet in Excel or Google Sheets.
  2. Delete all columns except:
    • The Email Name column — LO Email Message Name, Email Message/Social Post/Ad, or whatever your client uses for campaign + email + segment
    • Description — the column that says “logo header”, “link 1”, “footer button”, etc.
    • Final URL — the fully built tracking URL
  3. You may keep a Notes column for your own reference — the builder ignores it.
  4. Save as .csv (preferred) or .xlsx.
Why trim? The master spreadsheet often has 15+ columns with formulas, dropdowns, and extra metadata. Removing unused columns avoids parsing issues (e.g., trailing spaces in column headers, formula errors) and makes the file much smaller and easier to review.
Before (master spreadsheet) LO Email Message Name | Description | Source Code | Sub Source | Fiscal Year | Month | Campaign | Channel | Effort | Segment | UTM_Source | UTM_Medium | UTM_Campaign | UTM_Content | &autologin=true | ... | Final URL | Notes
After (trimmed for builder) LO Email Message Name | Description | Final URL | Notes

2 Spreadsheet Structure

After trimming, the spreadsheet should have the three required columns plus any optional reference columns.

  1. Row 1 must be the header row. Do not use multiple header rows (e.g., a category or grouping row above the actual column names). The builder reads row 1 as column headers and all subsequent rows as data.
  2. Column headers can vary in naming, but the builder matches columns by name, not by position. You can include as many additional columns as needed for your tracking workflow.
  3. Export as .xlsx or .csv — both formats are accepted. The builder always reads the first sheet of the workbook.
  4. Each row represents one tracked link for a specific email + segment + element combination.
Common mistake Spreadsheets with two header rows (e.g., a “category” row above the column names) will cause the builder to misread column names. The builder has a fallback that tries row 2 if row 1 doesn’t match, but this is unreliable — always put your column headers in row 1.

3 Required Columns

The builder uses three columns to resolve tracking URLs. The exact header name can vary — accepted alternatives are shown below:

Column Accepted Names Purpose
Email Name Email Message/Social Post/Ad, LO Email Message Name, Email Name, email_name Identifies the campaign, email number, segment, and (optionally) language. See “Email Name Format” below.
Description Description, description Identifies which element in the email receives this URL (e.g., logo header, link 1, footer button). See “Description Values” below.
Final URL Final URL, final_url The fully built tracking URL that gets inserted into the email HTML.
Note You can include any additional columns (Source Code, UTM_Source, UTM_Content, Campaign, Channel, Fiscal Year, etc.) for your own tracking purposes. The builder only needs Email Name, Description, and Final URL.

4 Email Name Format

The builder parses the Email Name column to extract the campaign, email number, and segment. These formats are supported:

Format Example Parsed As
Campaign – Email N – Segment 2026 Spouse Scholarship - Email 1 - Donors Campaign: “2026 Spouse Scholarship”, Email #1, Segment: “Donors”
Campaign – EN – Segment 25 Guardians Circle - E1 - nondonors & 1-249 Campaign: “25 Guardians Circle”, Email #1, Segment: “nondonors & 1-249”
Campaign Email N [Language] [Segment] WOCD Email 1 [English] [Engaged] Campaign: “WOCD”, Email #1, Language: English, Segment: “Engaged”
Campaign Email N (no segment) 2025 Spouse Scholarship Email 1 Campaign: “2025 Spouse Scholarship”, Email #1, Segment: all
Tips
  • Segment names are matched case-insensitively. The builder also strips “Audience” and “Segment” from copy-doc segment names when matching.
  • If a UTM spreadsheet has entries for multiple campaigns, the builder shows a campaign selector dropdown to pick the right one.
  • The builder uses fuzzy matching for segments, so minor typos in segment names (e.g., “Unngaged” vs. “Unengaged”) are handled automatically.
  • For bilingual campaigns (e.g., OCC), include [English] / [French] in the Email Name to distinguish language variants sharing the same email number.

5 Description Values

The Description column tells the builder which element in the email should receive each URL. Use these values (case-insensitive):

Description Email Element
logo header, header logo, logo Header logo link
header button, donate Header donate button (CGF)
feature image, header image, image 1 Banner / hero image link
link 1 – link 10 Body text links, in order of appearance. Can include descriptive suffixes (e.g., link 2 - stock).
button 1 – button 10 CTA buttons, in order of appearance
footer button, footer donate, footer Footer donate button (CGF)
Warning Unrecognized description values are skipped and surfaced as warnings in the builder UI. Check the warnings to make sure no URLs were missed.

6 Best Practices

  1. If a URL is missing for a link, the builder inserts {need UTM} as a placeholder — search for this in the output to catch gaps.
  2. Rows missing an Email Name or Final URL are skipped. Rows with an unparseable Email Name format are also skipped and counted in the warnings.
  3. The UTM spreadsheet is optional. If you don’t upload one, the builder generates all emails with {need UTM} placeholders that you can find-and-replace later.
  4. If multiple rows map to the same email + segment + description, the last row wins — avoid duplicates.
  5. Keep description values consistent across campaigns. The builder matches them case-insensitively.
  6. The builder shows UTM warnings on the upload screen when rows can’t be parsed or descriptions aren’t recognized. Always review these before generating.

Doing Good Digital — Email Builder System

Questions? Reach out to your project lead.