Generating Email Action Links

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

The Firebase Client 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 template-based 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, this page explains how to 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 bundle ID. This will try to open the link in an Apple app if it is installed. The app needs to be registered in the Console.
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) 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 (Apple 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.

Node.js

const actionCodeSettings = {
  // URL you want to redirect back to. The domain (www.example.com) for
  // this URL must be whitelisted in the Firebase Console.
  url: 'https://www.example.com/checkout?cartId=1234',
  // This must be true for email link sign-in.
  handleCodeInApp: true,
  iOS: {
    bundleId: 'com.example.ios',
  },
  android: {
    packageName: 'com.example.android',
    installApp: true,
    minimumVersion: '12',
  },
  // FDL custom domain.
  dynamicLinkDomain: 'coolapp.page.link',
};

Java

ActionCodeSettings actionCodeSettings = ActionCodeSettings.builder()
    .setUrl("https://www.example.com/checkout?cartId=1234")
    .setHandleCodeInApp(true)
    .setIosBundleId("com.example.ios")
    .setAndroidPackageName("com.example.android")
    .setAndroidInstallApp(true)
    .setAndroidMinimumVersion("12")
    .setDynamicLinkDomain("coolapp.page.link")
    .build();

Python

action_code_settings = auth.ActionCodeSettings(
    url='https://www.example.com/checkout?cartId=1234',
    handle_code_in_app=True,
    ios_bundle_id='com.example.ios',
    android_package_name='com.example.android',
    android_install_app=True,
    android_minimum_version='12',
    dynamic_link_domain='coolapp.page.link',
)

Go

actionCodeSettings := &auth.ActionCodeSettings{
	URL:                   "https://www.example.com/checkout?cartId=1234",
	HandleCodeInApp:       true,
	IOSBundleID:           "com.example.ios",
	AndroidPackageName:    "com.example.android",
	AndroidInstallApp:     true,
	AndroidMinimumVersion: "12",
	DynamicLinkDomain:     "coolapp.page.link",
}

C#

var actionCodeSettings = new ActionCodeSettings()
{
    Url = "https://www.example.com/checkout?cartId=1234",
    HandleCodeInApp = true,
    IosBundleId = "com.example.ios",
    AndroidPackageName = "com.example.android",
    AndroidInstallApp = true,
    AndroidMinimumVersion = "12",
    DynamicLinkDomain = "coolapp.page.link",
};

To learn more, see Passing State in Email Actions.

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.

Node.js

// Admin SDK API to generate the password reset link.
const userEmail = 'user@example.com';
getAuth()
  .generatePasswordResetLink(userEmail, actionCodeSettings)
  .then((link) => {
    // Construct password reset email template, embed the link and send
    // using custom SMTP server.
    return sendCustomPasswordResetEmail(userEmail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Java

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generatePasswordResetLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

Python

email = 'user@example.com'
link = auth.generate_password_reset_link(email, action_code_settings)
# Construct password reset email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

Go

email := "user@example.com"
link, err := client.PasswordResetLinkWithSettings(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct password reset template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

C#

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GeneratePasswordResetLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

After the link is generated, it can be inserted into the custom password reset email and then emailed to the corresponding user using a custom SMTP server.

If you are not using the default password reset landing page and building your own custom handler, see creating custom email action handlers.

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.

Node.js

// Admin SDK API to generate the email verification link.
const useremail = 'user@example.com';
getAuth()
  .generateEmailVerificationLink(useremail, actionCodeSettings)
  .then((link) => {
    // Construct email verification template, embed the link and send
    // using custom SMTP server.
    return sendCustomVerificationEmail(useremail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Java

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generateEmailVerificationLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

Python

email = 'user@example.com'
link = auth.generate_email_verification_link(email, action_code_settings)
# Construct email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

Go

email := "user@example.com"
link, err := client.EmailVerificationLinkWithSettings(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct email verification template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

C#

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GenerateEmailVerificationLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

After the link is generated, it can be inserted into the custom verification email and then emailed to the corresponding user using a custom SMTP server.

If you are not using the default email verification landing page and building your own custom handler, see creating custom email action handlers.

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.

Node.js

// Admin SDK API to generate the sign in with email link.
const useremail = 'user@example.com';
getAuth()
  .generateSignInWithEmailLink(useremail, actionCodeSettings)
  .then((link) => {
    // Construct sign-in with email link template, embed the link and
    // send using custom SMTP server.
    return sendSignInEmail(useremail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Java

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generateSignInWithEmailLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

Python

email = 'user@example.com'
link = auth.generate_sign_in_with_email_link(email, action_code_settings)
# Construct email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

Go

email := "user@example.com"
link, err := client.EmailSignInLink(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct sign-in with email link template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

C#

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GenerateSignInWithEmailLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

After the link is generated, it can be inserted into the custom sign-in email and then emailed to the corresponding user using a custom SMTP server.

Learn more about authenticating users with Firebase using email links. This will help provide information on how to complete sign-in after the user clicks the link and is redirected back to the app.