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 mobile link domain used for mobile app flows when constructing the email action link.
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 perform some tasks to detect these links from your mobile app. Refer to the instructions on how to configure mobile links for email actions.
To initialize an ActionCodeSettings
instance, provide the following data:
url
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
continueUrlquery parameter. - When the link is handled in the app directly, this is the
continueUrlquery parameter in the deep link of the Hosting link.
iOS
android
handleCodeInApp
linkDomain
PROJECT_ID
.firebaseapp.com
dynamicLinkDomain
The following example illustrates how to send an email verification link that
will open in a mobile app first. The deep link will contain the continue URL
payload https://www.example.com/checkout?cartId=1234
. The custom Hosting
link domain used is custom-domain.com
, which must be configured for use with Firebase Hosting
.
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'
,
},
// The domain must be configured in Firebase Hosting and owned by the project.
linkDomain
:
'custom-domain.com'
,
};
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"
,
LinkDomain
=
"coolapp.page.link"
,
};
To learn more, see Passing State in Email Actions .
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.
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 .
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.
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 .
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.
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.
