Summary
[!note] 📚 Pilotflow Pre-Launch Series
- The $50,000 Gmail Add-on Myth
- Gmail OAuth Scopes Decoded
- Pre-Development Codebase Review
- Legal Documents in 15 Minutes ← you are here
In the previous post, the pre-development work was done: codebase reviewed, architecture decided, bugs logged. Now the product needed to be legally publishable.
Google requires a Privacy Policy URL and Terms of Service URL before you can configure an OAuth consent screen. Both links appear on the consent screen that users see when they install your add-on. They’re not optional — and they’re not decorative. Google reviewers read them.
The first time I did this (for Notiwise), it took roughly two hours. For Pilotflow, it took fifteen minutes.
Why Legal Documents Matter More Than You Think
Vague, generic privacy policies are a common reason Google rejects Workspace Marketplace submissions. A policy that says “we may collect data to improve our services” reads very differently to a reviewer than one that says “we read the subject, sender, and date of emails in your inbox. We do not store email body content.”
Specificity matters. Accuracy matters. And for add-ons requesting sensitive Gmail permissions, users clicking those links before consenting want to understand exactly what the add-on can and cannot do with their inbox.
The documents serve two audiences simultaneously: Google’s reviewers and your users. Generic templates fail both.
The Notiwise Template Investment
When building Notiwise, I spent two hours producing the legal documents from scratch:
- Finding appropriate SaaS templates
- Adapting them for Google Workspace requirements
- Making them accurate for what the add-on actually does
- Formatting them for the Jekyll corporate website
- Deploying and verifying the URLs
That two-hour session produced more than documents — it produced reusable Handlebars templates with product-specific content replaced by ,, `` placeholders. The format, structure, section order, and scope-specific language patterns were all captured.
Think of it as building a kitchen the first time versus the second. The first kitchen requires designing everything. Every kitchen after inherits the design — you just furnish the rooms.
The Pilotflow Process: 4 Steps, 15 Minutes
Step 1: Locate the Notiwise templates (3 minutes)
The templates were documented in the Notiwise project file. Finding them took less time than opening a blank document.
Step 2: Identify the substitutions needed (8 minutes)
Pilotflow needed changes in two categories only:
Product identity: Notiwise → Pilotflow by Zippy, URLs and support email updated accordingly.
Scope-specific language: The Privacy Policy described what each OAuth scope allows. Pilotflow’s seven scopes differed from Notiwise’s — so the scope descriptions were rewritten to match.
Because the pre-development OAuth analysis (covered in post 2) had documented exactly what each scope accesses, this was mechanical substitution — not judgment work.
Step 3: Deploy via GitHub API (4 minutes)
The corporate website (BrightSoftwares/corporate-website) is a Jekyll site. Deploying content doesn’t require cloning it locally — the GitHub Contents API creates files directly:
CONTENT=$(base64 -w 0 pilotflow-privacy-policy.md)
curl -s -X PUT \
-H "Authorization: token ${GITHUB_TOKEN}" \
-H "Content-Type: application/json" \
"https://api.github.com/repos/BrightSoftwares/corporate-website/contents/_pages/pilotflow-by-zippy-privacy-policy.md" \
-d "{\"message\": \"Add Pilotflow privacy policy\", \"content\": \"${CONTENT}\"}"
Both files — Privacy Policy and Terms of Service — deployed to predictable URLs:
https://bright-softwares.com/pilotflow-by-zippy/privacy/https://bright-softwares.com/pilotflow-by-zippy/terms/
Step 4: Verify (0 minutes extra, built into the deploy flow)
After Jekyll builds (typically 2–3 minutes post-push), a quick HTTP check confirms both URLs return 200. These URLs go directly into the Google Cloud Console OAuth consent screen configuration.
What Gmail Add-on Legal Documents Must Actually Cover
For anyone building a Gmail add-on’s legal documentation for the first time, here’s what specificity requires:
Privacy Policy — the five sections that matter:
-
What you access: List each OAuth scope in plain language. “We can view and modify the labels applied to your email messages” (for
gmail.labels), not “we access Gmail data.” -
What you store: If you store nothing beyond PropertiesService keys, say so explicitly. Users fear email content being stored. If you don’t store it, state that directly.
-
What you do with it: The functional description must match the actual add-on behavior exactly.
-
Data deletion: What happens when a user uninstalls? For Apps Script add-ons, PropertiesService keys are cleared. Document the specific mechanism.
-
Contact: A working email address you actually monitor. Not a placeholder.
Terms of Service — the section most add-ons miss:
Liability clauses specific to the add-on’s actions. For Pilotflow, this included explicit clauses about email archiving (what happens if an archive action moves an email a user still needed) and forwarding (what happens if a forwarding rule sends something to an unintended recipient). Generic ToS templates don’t anticipate these scenarios.
Key Takeaways
- Google reviewers read your legal documents. Generic policies are a rejection risk.
- The first time you create legal docs for a Gmail add-on costs ~2 hours. Every subsequent add-on costs ~15 minutes — if you templated the first set properly.
- The GitHub Contents API lets you deploy Jekyll content without cloning the repository. Valuable for any automation or headless workflow.
- Scope-specific language in your Privacy Policy requires knowing exactly what each scope accesses — which is why the OAuth analysis from earlier in the series matters.
The Pilotflow Series — Complete
This four-post series covered the complete pre-launch research and setup for a Gmail add-on:
- The $50K CASA Myth — Correcting the certification cost and understanding when it applies
- OAuth Scopes Decoded — The three-tier classification and the one-word distinction that matters most
- Pre-Development Codebase Review — Reading before writing, and the bug that was waiting
- Legal Documents in 15 Minutes ← you just read this
Next up: building the asset generation system that creates logos, blog images, and social cards for every product in the portfolio.
← Previous: Pre-Development Codebase Review
— Kékéli
