How to change the rest-auth reset password email to a custom HTML template

We have previously discussed Django REST framework and dj-rest-auth, both effective libraries for Django where you can easily create rest APIs and handle user authentication.

In this post, we will focus particularly on dj-rest-auth and its built-in reset password functionality. If users want to reset their password they must submit a reset password request, and receive an email with a link to a reset page.

This feature is provided by the dj-rest-auth library but the email sent to its users is in plain text, while the link that comes in it is from a built-in dj-rest-auth endpoint. This may be exactly what you want in some cases, but it’s not always a good fit.

If you want to change this email content, the process is well documented but only if you want to change it to a plain text file. If you want to change to a custom HTML template, there is not much information on this.


For this instance, we will assume that you have python, Django, Django REST framework, and dj-rest-auth installed for a project ready to make these changes. In my example, I made a very simple project with just one app called API, and the following layout:

API Layout

As you can see above, I have a templates folder in which I made a new folder called registration with a file called custom_reset_confirm.html within.

The context in the HTML email template looks like this:

Context in the HTML Email Template

As you may have noticed, the content is pretty much the same as in the default email, and for the sake of simplicity, I didn’t add a lot of styles, just some bold and italic text as well as a greeting in bigger font size.

The relevant variables like site_name, domain, and such, will be automatically assigned values passed on the context to the template.

Changing the default email

Now that we have our template, what we need to do next is to indicate that this is what we want to send our users when they request a password reset.

To do this, we have to define a serializer that inherits from dj-rest-auth’s PasswordResetSerializer and overwrite its get_email_options method, and then use that serializer instead of the default one.

So, first, we will define the new serializer:

New Password Reset Serializer
Overwrite get_email_options method

And then in our, we will indicate that this is the serializer we want to use:

indicating the serializer we want to use

Now, if you send a reset password request you should receive something like this:

In my case, because I’m running this project locally, it uses localhost:8000 for the site_name.

Now, let’s say that you want to add something else to this email, some information that may change and you wouldn’t be able to hardcode it on the template itself.

Let’s take adding a link to social media, in that case, I can add the key extra_email_context to the dictionary that get_email_options returns, and as its value a dictionary with the extra context.

For example, let’s replace The {{ site_name }} team at the end with a fake URL:

Example of replacing The {{ site_name }} team at the end with a fake URL

And now define the value of social_media_url in the serializer.

define the value of social_media_url in the serializer

It is also possible to overwrite default values like site_name in the same way by using extra_email_context, but it is not recommended to do so.

Finally, here is some code to make a simple but much prettier template so you can appreciate how much more visually appealing your email can be:

Simple code to make your email visually appealing
Simple code to make your email visually appealing
Simple code to make your email visually appealing

And now, this is how it will look:


In this blog post, you learned how to overwrite any email template in dj-rest-auth. While we focused on the reset password feature, the same principle can be used in other cases.

We replaced the reset password email with a new HTML one by defining a custom PasswordResetSerializer. We also updated the email content by dynamically using the get_email_options method of the PasswordResetSerializer base class.

I hope you enjoyed this latest post and found it useful. Thank you for reading and stay tuned for more similar content.

Want to work with Jorge Michelena ?
We are hiring :)

When you think of design thinking, what comes to mind? You might imagine stock images of people in suits smiling […]
November 25
5 min read
Slicing and atomization have become popular terms in the software industry, but many developers may need help understanding their true […]
November 22
5 min read
In recent years, automating software quality tests has become widely popular in the tech industry. Current automation tools allow us […]
November 21
5 min read
While I was in a session with one of my mentors some time ago, we did an exercise called Ikigai, […]
November 18
5 min read
Did you know that 76% of internet users access social media for product research? Your target audience is likely part […]
November 9
5 min read