> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/account/email-links.md).

# Email and SMS links

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/email-links.md).
{% endhint %}

Invitations, password resets and profile checks reach people as **links** in emails and text messages. Each link carries one ID, the **ctx** value, and goes through one Snapfix page on `dl.snapfix.com`. Nothing in the address says what kind of link it is; the server looks the ID up. On a phone the page opens the installed app, or the app store if the app is missing. On a computer it opens the web app's **account access** page. That page reads the link and either signs the person in or sends them to choose a password.

## Rules

### Kinds of link

* A link is one of four kinds: a QR invitation (`qrcode-invitation`), an invitation (`user-invitation`), a password reset (`reset_password`), or a profile check (`verify_profile`) that finishes a QR sign-up (authpy @ 5d5758661c, `model/feature_token_ops.py:3546-3618`).
* An unknown or deleted link is refused as "invalid reference" (`feature_token_ops.py:3548-3550`).

### Opening a link

* Every open is counted, even one that is then refused (`feature_token_ops.py:3552-3553`).
* A QR invitation has no time limit; the one-hour check is commented out. It stops working once someone has finished signing up with it ("invitation expired"). A signed-out person is told to create a profile; a signed-in person joins the link's sites and groups (`feature_token_ops.py:3555-3564`).
* An invitation works while its invitation is pending, exists or is onboarded. It has no time limit and no use check when it is opened (`feature_token_ops.py:3565-3581`). Setting the password from it on the web counts the link as used and tells the inviter (php-apis @ aee9175122, `cognito.functions.php:1202-1207`).
* A reset link works for 15 minutes, only for a signed-out person, and only until it is used ([Password reset](https://docs.snapfix.com/product/features/account/password-reset.md#the-reset-link)).
* Opening a profile-check link creates the account from the stored sign-up form, before the person signs in, and counts the original QR link as used (`feature_token_ops.py:3598-3615`). That form holds the password in plain text ([Sign up by QR invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/qr-sign-up.md)).
* The read route also accepts expired sign-in tokens ([Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md)).

### The link page

* [Deep link](https://docs.snapfix.com/how-the-apps-work/screens/account/deep-link.md) is one public page for all links. Besides `ctx` it reads `env` (local, test or staging; anything else means production), which picks the web app host, and `hasWebView`, which forces the web app ([Deep link](https://docs.snapfix.com/how-the-apps-work/screens/account/deep-link.md#inputs)).
* On a computer, or with `hasWebView`, the page goes to [Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md) in the same window (dynamic-link @ 4d1cd0eb62, `src/app/components/main/main.component.ts:51-62`).
* On a phone the page opens `snapfix://open?ctx=` and, after 1.5 seconds, the Play Store (with the `ctx` as referrer) or the App Store. The timer fires whether or not the app opened, so a store page can open behind the app (`main.component.ts:66-80`).
* The page is set up for iOS universal links and Android app links, so a phone with the app can open matching links in the app directly (`public/.well-known/`).
* For a staging link, the host is not the staging site \[[ASK-8](https://github.com/snapfix/docs/blob/main/ASK.md#ask-8-confirm-the-environments)].
* A link opened without its `ctx` shows "404", "Look like you're lost" and "the page you are looking for not avaible!", and still redirects with the text `ctx=undefined`.

### Signing in from a link (web)

* [Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md) shows only a spinner. It reads the link, then asks the server to check it and to return tokens for the account named by the link's email, or by its phone digits ([Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md#actions)).
* The check looks only for the link. It does not check that the link belongs to that account (`model/feature_user_auth.py:980-987`). The same call marks the account's email and phone as verified (`feature_user_auth.py:995-1003`).
* The web makes these calls with the shared login built into its front end ([Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md#actions)).
* A profile-check link, or an account with no temporary password, is signed in and opens Fix. Any other link opens the page to choose a password ([Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md#actions)).
* Failures show an alert ("Something went wrong" without `ctx`; the server's message, such as "invalid reference", for a bad link) and go to sign-in ([Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md#states)).

### Opening in the apps

* On Android, the splash screen passes a pending link to the app's link handler ([App launch](https://docs.snapfix.com/product/features/account/app-launch.md#where-the-app-goes-next)). On iOS, invitation links open the in-app password screens ([Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md)).

### Making QR invitation links

* QR invitation links are made and replaced through `POST` and `PUT /v1/app/generate-dynamic-link` ([Account API](https://docs.snapfix.com/engineering-reference/api/account.md#post-v1appgenerate-dynamic-link)).
* Making one does not check that the caller belongs to the named sites or groups. Every invitation must name groups, so the site-wide branch in the code is never used \[[ASK-33](https://github.com/snapfix/docs/blob/main/ASK.md#ask-33-are-invitations-for-a-whole-site-no-group-wanted)] (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Requests/v1/DynamicLinkRequest.php:18-27`).
* Replacing one copies it and deletes the old link, so a printed QR code stops working. The replace call does not check who owns the link (`DynamicLinkController.php:85-118`).

## Flow

```mermaid
flowchart TD
  link["Link in an email or text"] --> page["Snapfix link page"]
  page --> device{"Phone or computer?"}
  device -- "phone" --> installed{"App installed?"}
  installed -- "yes" --> app["App opens the link"]
  app --> screen["App screen for the kind of link"]
  installed -- "no, after 1.5 seconds" --> store["App store page"]
  device -- "computer or web view" --> access["Account access page"]
  access --> read["Read the link"]
  read -- "refused" --> errs["Error alert, then sign-in"]
  read -- "accepted" --> check["Check the link and get tokens"]
  check -- "refused" --> errs
  check -- "profile check, or no temporary password" --> fix["Signed in: Fix"]
  check -- "invitation or reset" --> setpw["Choose a new password"]
```

## Platforms

| Capability                         | Web                                                                | iOS                                      | Android                                              |
| ---------------------------------- | ------------------------------------------------------------------ | ---------------------------------------- | ---------------------------------------------------- |
| Link opens the app                 | not applicable: the link page hands phones to the app or the store | yes, universal links or `snapfix://open` | yes, app links or `snapfix://open`                   |
| Store page when the app is missing | not applicable                                                     | App Store after 1.5 seconds              | Play Store after 1.5 seconds, `ctx` kept as referrer |
| Reset link                         | account access, then a new password                                | reset screen                             | reset screen                                         |
| Invitation link                    | account access, then a new password                                | "Accept invitation"                      | "Accept invitation"                                  |
| QR invitation link                 | "Something went wrong"                                             | "Sign up by QR invitation"               | "Sign up by QR invitation"                           |
| Profile-check link                 | the account is created, and the person is signed in                | "Accept invitation"                      | "Accept invitation"                                  |

## Screens

* [Deep link](https://docs.snapfix.com/how-the-apps-work/screens/account/deep-link.md)
* [Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md)
* [Reset your password](https://docs.snapfix.com/how-the-apps-work/screens/account/reset-password.md), [Accept invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/accept-invitation.md) and [Sign up by QR invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/qr-sign-up.md): the mobile screens that links open

## API and data

* [Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md): `GET /dl-ctx/{dynamicLinkUUID}` reads the link, counts the open, and creates the account for a profile-check link. `POST /validate-username-v3` checks the link and returns tokens.
* [Account API](https://docs.snapfix.com/engineering-reference/api/account.md): [`POST /v1/app/generate-dynamic-link`](https://docs.snapfix.com/engineering-reference/api/account.md#post-v1appgenerate-dynamic-link) makes a QR invitation link. [`PUT /v1/app/generate-dynamic-link/{uuid}`](https://docs.snapfix.com/engineering-reference/api/account.md#put-v1appgenerate-dynamic-linkuuid) replaces it.
* Tables: [`dynamiclink`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink.md) (each link, its kind, opens and uses), [`dynamiclink_invitation`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_invitation.md) (the sites, groups and roles an invitation grants) and [`dynamiclink_user`](https://docs.snapfix.com/engineering-reference/db/tables/dynamiclink_user.md) (each invited person's status).

## Depends on

* [Password reset](https://docs.snapfix.com/product/features/account/password-reset.md): the reset link and the new-password page.
* [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md): the sign-in the link ends in, and the session it starts.
* [Joining a site](https://docs.snapfix.com/product/features/onboarding/join-site.md): invitations and QR sign-up.
* [Site users](https://docs.snapfix.com/product/features/console/site-users.md): the invitations that site admins send, and the add-user QR sheet.
* [App launch](https://docs.snapfix.com/product/features/account/app-launch.md): links that open at launch on Android.

## Edge cases

* **Offline:** the link page and account access need a connection; the requests fail and the error alert shows ([Account access](https://docs.snapfix.com/how-the-apps-work/screens/account/account-access.md#states)).
* **Missing `ctx`:** the link page shows its "404" text, and account access shows "Something went wrong" and goes to sign-in.
* **Unknown, used or expired link:** "invalid reference", or "reference expired" for an old reset link, then sign-in.
* **QR invitation in a browser:** the web shows "Something went wrong" and does not explain that the invitation continues in the app.
* **App missing:** the store opens, and the `ctx` travels along so the app can pick the link up after install.
* **Time zones:** None.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/account/email-links.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
