TMA — Email Deep-Link Route Map (OneLink)

How to read a row

Each OneLink email link sets one deep_link_value. On a phone with the app → it opens the Opens screen. On a phone without the app → App/Play Store → after install it lands on that same screen (deferred). On a desktop / laptop → it opens the Web fallback URL. Unknown or empty value → the app home (today). Never crash on an unmapped link.

The route map

`deep_link_value`	Opens (screen)	App route (proposed — RN confirms)	Sub-params	Web fallback (desktop / no app)	Used by (email / lifecycle)
today default	Today / Home tab — the progression room	`/(app)/(tabs)/home` confirmed	—	web app home / `themovementathlete.com`	Welcome, generic "open the app", re-engagement. The fallback for any unknown value.
workout	The day's workout (or a specific one)	Home → workout player confirm	`sub1` = `workout_id` (omit = today's)	web app workout, else app home	"Your 3 free workouts are waiting" · no-workout nudge (Task 11 · segment B) · streak / return.
resume_assessment	Resume / start the assessment (skill-tree placement)	assessment route confirm	—	web quiz / assessment (`/start-training`)	Welcome "finish setup" · survey-unfinished (Task 11 · segment A).
upgrade	In-app paywall / upgrade	`/(app)/pages/upgradePremium` confirmed	`sub1` = offer / plan (optional)	web checkout (offer URL, e.g. `/30trial` / `/start-training`)	Trial nudges · paywall-seen-no-trial (Task 11 · segment D) · promos. Post-RN‑4 this renders the RevenueCat remote paywall.
update_payment high value	Update card / billing	store billing mgmt (app subs) / in-app billing route confirm	—	web billing portal (account → billing)	Dunning / failed-card recovery (Task 21). Never send dunning to home — this row is why the add-on pays for itself.
skills	Skill tree (or a specific skill)	skills route confirm	`sub1` = `skill_id` (optional)	web skills	Progression / education emails · "you unlocked…".
settings (optional)	Settings (e.g. notifications)	settings route confirm	`sub1` = section (optional)	—	Account / notification-permission prompts. Lower priority.

confirmed route verified in the live MovementAthlete-RN repo · confirm proposed — RN team confirms the exact route in the confirm-pass before wiring.

The four rules (locked)

Default: unknown / empty deep_link_value → today (home). Never crash on an unmapped link.
Deferred (new install): apply the stored value on first launch after account creation / onboarding completes — so a brand-new user isn't dropped mid-paywall before they have an account. (update_payment is only ever sent to existing subscribers, so it's always a direct open.)
Desktop / no app: handled by the OneLink's web fallback URL — so every value must have a web fallback set in the OneLink template (Task 26). This is also the "link to web now" interim: where a good web destination exists, an email can point there today with no app release.
Keys are locked (like Amplitude event names): use the deep_link_value strings verbatim, and add a new row to this table before using a new value in an email.

How a link is built

OneLink base (Task 26)      https://go.themovementathlete.com/<template>
  ?deep_link_value=workout        ← the key from the table
  &deep_link_sub1=1234            ← optional id / offer
  &af_web_dp=https://…            ← web fallback (desktop / no app)
  &pid=email&c=<campaign>&af_channel=<sequence>   ← attribution (which email drove it)

The email team uses the OneLink URL pattern (Task 26 provides it); they only choose the deep_link_value + optional sub-param. The attribution params (pid/c/af_channel) are what make "which email drove revenue" answerable — the same build, one artifact.

Who uses this table

Nic (Task 26 · no release) — sets each row's web fallback in the OneLink template + wires the Customer.io / ActiveCampaign ESP integration.
RN team (Task 24 / RN‑6 · release) — implements the deep_link_value → app route mapping in DeepLinkService, and confirms the confirm routes.
Email team — picks the deep_link_value per email link. Nothing else.

TMA Email Deep-Link Route Map v1.0 · 14 Jul 2026 · Lives inside the Analytics Master Brief site · Change control: add a row here (and tell the RN team) before any new deep_link_value ships in an email.