Generating Email Action Links

Mobile apps sometimes need to interact with users and prompt them to take
certain actions by sending emails.

The Firebase Admin SDKs
provide the ability to send users emails containing
links they can use for password resets, email address verification, and
email-based sign-in. These emails are sent by Google and have limited
customizability.

If you want to instead use your own email templates and your own email delivery
service, you can use the Firebase Admin SDK to programmatically generate the
action links for the above flows, which you can include in emails to your users.

This comes with the following benefits:

Customize email templates. This includes the ability to add new styles and
custom branding, change wording and logos, address users by first name instead
of full name, and so on.

Apply different templates depending on context. For example, if the user is
verifying their email to subscribe to a newsletter, the context may need to be
provided in the email content. Another example is email link sign in: in one
scenario this may be triggered by the same user, or as an invite by another
user. The context would need to be included in the email.

Localize customized email templates.

Ability to generate the link from a secure server environment.

Ability to customize how the link is to be opened, through a mobile app or a
browser, and how to pass additional state information, etc.

Ability to customize the dynamic link domain used for mobile app flows when
constructing the email action link, and even specify a different dynamic link
domain depending on context or mobile app.

Initialize ActionCodeSettings

Before you can generate an email action link, you may need to initialize an
ActionCodeSettings instance.

ActionCodeSettings allow you to pass additional state via a continue URL which
is accessible after the user clicks the email link. This also provides the user
the ability to go back to the app after the action is completed. In addition,
you can specify whether to handle the email action link directly from a mobile
application when it is installed or from a browser.

For links that are meant to be opened via a mobile app, you’ll need to enable
Firebase Dynamic Links and perform some tasks to detect these links from your
mobile app. Refer to the instructions on how to
configure Firebase Dynamic Links
for email actions.

To initialize an ActionCodeSettings instance, provide the following data:

Parameter

Type

Description

url

string

Sets the link (state/continue URL) which has different meanings
in different contexts:

When the link is handled in the web action widgets, this is the deep
link in the continueUrl query parameter.

When the link is handled in the app directly, this is the
continueUrl query parameter in the deep link of the
Dynamic Link.

iOS

({bundleId: string}|undefined)

Sets the iOS bundle ID. This will try to open the link in an iOS app if
it is installed. The iOS app needs to be registered in the Console.

Sets the Android package name. This will try to open the link in an
android app if it is installed. If installApp is passed, it
specifies whether to install the Android app if the device supports it and
the app is not already installed. If this field is provided without a
packageName, an error is thrown explaining that the
packageName must be provided in conjunction with this field.
If minimumVersion is specified, and an older version of the
app is installed, the user is taken to the Play Store to upgrade the app.
The Android app needs to be registered in the Console.

handleCodeInApp

(boolean|undefined)

Whether the email action link will be opened in a mobile app or a web
link first. The default is false. When set to true, the action code link
will be be sent as a Universal Link or Android App Link and will be opened
by the app if installed. In the false case, the code will be sent to the
web widget first and then on continue will redirect to the app if
installed.

dynamicLinkDomain

(string|undefined)

Sets the dynamic link domain (or subdomain) to use for the current link
if it is to be opened using Firebase Dynamic Links. As multiple dynamic
link domains can be configured per project, this field provides the
ability to explicitly choose one. If none is provided, the oldest domain
is used by default.

The following example illustrates how to send an email verification link that
will open in a mobile app first as a Firebase Dynamic Link (iOS
app com.example.ios or Android app com.example.android where the app will
install if not already installed and the minimum version is 12). The deep link
will contain the continue URL payload
https://www.example.com/checkout?cartId=1234. The dynamic link domain used is
coolapp.page.link, which must be configured for use with Firebase Dynamic
Links.

Generate password reset email link

To generate a password reset link, provide the existing user’s email and an
optional ActionCodeSettings object. The operation will resolve with the email
action link. The email used must belong to an existing user.

Generate email verification link

To generate an email verification link, provide the existing user’s unverified
email and an optional ActionCodeSettings object. The operation will resolve
with the email action link.
The email used must belong to an existing user.

Generate email link for sign-in

Before you can authenticate users with email link sign-in, you will need to
enable email link sign-in
for your Firebase project.

To generate a sign-in link, provide the user’s email and an ActionCodeSettings
object. The ActionCodeSettings object is required in this case to provide
information on where to return the user after the link is clicked for sign-in
completion. The operation will resolve with the email action link.

Unlike password reset and email verification, the email used does not
necessarily need to belong to an existing user, as this operation can be used to
sign up new users into your app via email link.