Customizing Cognito verification emails with HTML using AWS Lambda

This has become very common to use AWS Cognito as an authentication system in modern days. Using Cognito, when a user signs up or gets an invitation from another user, he gets an email with password and verification codes. But the email is in simple plain text. But we can easily configure a lambda function that can customize and beautify this email according to our needs.

To configure the lambda, first, we have to understand the states when we can actually trigger a lambda from Cognito. These states are (source):

1. CustomMessage_SignUp : Custom message — To send the confirmation code post-sign-up.
2. CustomMessage_AdminCreateUser : Custom message — To send the temporary password to a new user.
3. CustomMessage_ResendCode : Custom message — To resend the confirmation code to an existing user.
4. CustomMessage_ForgotPassword : Custom message — To send the confirmation code for Forgot Password request.
5. CustomMessage_UpdateUserAttribute : Custom message — When a user’s email or phone number is changed, this trigger sends a verification code automatically to the user. Cannot be used for other attributes.
6. CustomMessage_VerifyUserAttribute : Custom message — This trigger sends a verification code to the user when they manually request it for a new email or phone number.
7. CustomMessage_Authentication : Custom message — To send MFA code during authentication.

For convenience, we will only focus on the first two and hope that you can easily configure for the others. Now let’s configure the lambda.

Go to the Lambda console and click create a function and give it a name and node version then create it. Now for the code part, follow the below:

Let’s go through the code. The event in the lambda will contain all the things we need for an email. event.triggerSource will contain the states described above. So based on this trigger source, we will construct different email template. You can see in the code that two functions template and templateInvite actually return some HTML code as a string. One thing to remember that you should use inline CSS in the HTML, otherwise there may be some problems. Another thing to notice that, for the CustomMessage_AdminCreateUser state, always use the email addresses from the event.request.usernameParameter, otherwise Cognito will throw a silent error and you will not be able to debug what is actually happened. And always include only the body tag of the HTML. You can see in the code I have done that.

Now, let's configure the Cognito to call this lambda whenever a new user is registered. Go to your Cognito user pool console, and click on the Trigger from the menu tab. Now select the lambda function in the Custom message menu just like below:

Selecting the lambda in the Cognito trigger

Now you will see whenever a new user registers or gets a new invitation, he will get your customize mail. You can actually customize the message for the SMS also in the event.response.smsMessage parameter.

Custom email for confirm signup

Custom email for the invitation