EMAIL_VOICE_GUIDE.md — h.work
The one-page voice & word-list reference for every transactional email h.work sends. Authored for #1254 (copy rewrite); the copy in
api/src/email/email.service.tsis written to this guide.Reads alongside TRANSACTIONAL_EMAIL_IA.md (audience IA + per-email specs), branding.md, and the repository
GLOSSARY.mdterminology table.Last updated: 2026-06-24.
1. The voice in one line
Warm, precise, never robotic, never cute. Every email sounds like a thoughtful person at a premium service wrote it — not a form letter, not a growth-hack, not an engineer in a hurry.
The bar this replaces: "You've been invited to join h.work on h.work. Click below to accept the invitation and set up your account." — bland, off-brand, structurally broken. The bar we hold to: copy a real person would be glad to receive.
2. Five principles
- Lead with the person, not the system. Say what changed for them ("Your workspace is live") before what the platform did ("The system has activated your account").
- One idea per sentence; one job per email. Each email has a single purpose and a single primary action. Cut every sentence that doesn't move the reader toward it.
- Precise beats effusive. Warmth comes from clarity and respect for the reader's time, not from adjectives or punctuation. We never manufacture excitement with exclamation marks.
- Plain English, full sentences. No jargon, no internal shorthand, no concatenated fragments. Write sentences that survive translation — localization-ready means no string-stitching (§6).
- Tell them what happens next. Never end on a dead end. State the next step, the timeline, or where to get help.
3. Do / Don't
| Don't | Do |
|---|---|
| "You've been invited to join h.work on h.work." | "You're invited to join Acme Financial on h.work." |
| "Click below to accept the invitation and set up your account." | "Accept your invitation below — it takes about a minute." |
| "Your trial is ENDING SOON!!!" | "Your h.work trial ends in 3 days." |
| "Your most recent payment failed." (no path forward) | "Your latest payment didn't go through — here's how to fix it." |
| "Hi there," / "Hi," / "Hello!" (mixed across emails) | One greeting per audience (§5), used consistently. |
| "completed joining" / "We couldn't process your payment" (system-first) | "verify your email" / "Your latest payment didn't go through" (reader-first) |
| Emoji in a heading ("You're matched 🎉") | Carry the warmth in the words: "You've been matched." |
4. Subject lines
- Under 60 characters. Front-load the meaning so it survives truncation on mobile.
- Sentence case. No Title Case, no ALL-CAPS (acronyms like OTP / KYC excepted).
- No exclamation marks. No emoji.
- Name the real thing. Never the platform in the org slot ("…on h.work on h.work"). When there is no client org (staff invites), name the team, not a placeholder.
- Audience-appropriate: Client subjects explain; Expert subjects state status; AM/Ops subjects read as internal signal; System subjects are literal ("Your h.work verification code").
5. Greetings & signoffs (per audience)
Inherited from IA §2.1 / §6.5. Use exactly these so the catalog stops drifting between "Hi," / "Hi there," / "Hello".
| Audience | Greeting | Signoff |
|---|---|---|
| CLIENT | Hi {first name}, when known, else Hi there, | — the h.work team |
| EXPERT | Hi {name}, | — the h.work Expert Network team |
| AM / Ops (internal) | none — open on the signal | none, or h.work Ops |
| SYSTEM (OTP, reset) | none — open on the action | none |
6. Localization-ready writing
- No concatenated strings. Build full sentences in the template; never assemble copy from clauses joined at runtime. Branch whole sentences instead (e.g. the domain-aware and trial-countdown variants each carry their own complete sentence).
- No trailing-arrow glyphs in labels. Button labels are verbs ("Accept invitation"), not "Accept →".
- Keep variables to nouns (names, orgs, dates, codes). Don't interpolate verbs or sentence fragments that reorder under translation.
7. Word list
Aligns with the repository GLOSSARY.md. Wrong terminology in user-facing copy is a
review block.
| Use | Not | Where |
|---|---|---|
| Specialist | agent, bot, assistant | The AI persona a client works with |
| Expert | specialist (for a human), reviewer-bot | The Humanity Protocol human reviewer |
| member | user, seat | Client-facing copy for people in a client org |
| applicant | candidate | Expert recruiting-funnel copy |
| client / your team / your workspace | tenant, account, workspace-the-noun | What the client org is, in client copy |
| Account Manager | account rep | The HP person managing the client |
| h.work (lowercase, with the dot) | Hwork, H.Work, HWork | Always |
| the h.work Expert Network | the network, the talent pool | Expert-audience name for the program |
| verify your email | complete joining | OTP / verification context (it's reused for login + reset) |
| invitation / invite (noun) | invitiation, inv | — |
| check-in | sync, call (when it's the recurring one) | Weekly client check-in |
8. Tone by moment
- Welcoming (invite, welcome, kickoff): warm and low-friction; say what h.work is in one line for people who've never heard of it; make the first action feel small.
- Status (qualified, assignment, completion): clear and genuine; state the change, then what's next. No hype, no emoji — the good news carries itself.
- Recovery (trial ending, payment failed, reminders): calm and specific; name the likely-benign cause, give one clear action, offer help. Never alarmist, never guilt-trip.
- Security (OTP, password reset): neutral and minimal; one sentence of context, the code, the expiry, and how to tell if it wasn't them.
- Internal (AM completion, KYC failure): operational and scannable; data first, no reassurance copy.
For the per-email intent, skeleton, and CTA, see TRANSACTIONAL_EMAIL_IA.md §4.