Deep links for transactional email

Overview

Transactional email is where deep linking pays off most, because the recipient almost always already has your app. Someone asking for a password reset installed your app first. Sending them to a mobile browser to sign in, when the app is sitting on their home screen, is the exact failure deep linking exists to prevent.

It is also the cheapest place to apply it. A campaign link is created once by hand; a password-reset link is generated programmatically, forever. This guide shows the URL shape that makes that work with a single LinkSense link record.

When the app is installed

LinkSense claims every path on your project subdomain in the Apple App Site Association file, and the Android Digital Asset Links file has no path filter at all. iOS caches that association when your app is installed and matches it on-device.

So when a recipient taps https://acme.linksense.net/reset?token=abc123 on a phone with your app installed, the operating system opens your app and hands it the full URL — path and query string intact. LinkSense is never contacted. You do not need to create a link record per email, per user, or per token.

// iOS — the OS hands you the URL that was tapped, intact.
func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else { return false }
 
    // https://acme.linksense.net/reset?token=abc123
    // Route it yourself — LinkSense does not store a screen for the link.
    router.handle(url)
    return true
}

Put the token in a query parameter

The URL shape only matters for recipients who do not have your app — a laptop, a new phone, someone who uninstalled. For them the link reaches LinkSense, and LinkSense has to find a matching link record.

It looks up the full path and query string first, then falls back to the path on its own. That fallback is what lets one record serve unlimited recipients — but only if the variable part of your URL is in the query string.

https://acme.linksense.net/reset?token=abc123
 
// One link record, custom path "reset".
// Serves every recipient, forever. No API call at send time.

https://acme.linksense.net/reset/abc123
 
// No link record matches. The visitor gets a 404 —
// with the reset token rendered into the page.

Setting it up

// Your existing password-reset mail, unchanged except for the URL.
const token = await createResetToken(user.id);
 
await mailer.send({
  to: user.email,
  subject: 'Reset your password',
  html: renderTemplate({
    // Note the query parameter. One LinkSense link record at
    // custom path "reset" backs every message you ever send.
    resetUrl: `https://acme.linksense.net/reset?token=${token}`,
  }),
});

Two limits to know about

Query parameters are not forwarded to the app store. When an uninstalled visitor is routed onward, the store URL is used as configured; only the Google Play install referrer is appended. Your token survives to your app on the app-open path, not through a store install.

There is no wildcard or prefix matching. Link lookup is an exact match on the path, so /reset does not also match /reset/anything. Pattern routing is not something you can configure today.

Before you send: check your ESP

Most email providers rewrite every link in your message to their own click-tracking domain. That domain is not in the app-site-association file LinkSense serves, so the operating system has no app to open and the link falls back to a browser — even though everything above is configured correctly.

This is the single most common reason deep links fail in email, and it is worth checking before you ship.