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 CLAUDE.md terminology 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 CLAUDE.md terminology table. 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.