Customizing Emails

• Intro       • Settings       • Forms       • Emails       • Advanced      

Customizing EmailAdapters

Flask-User ships with the following EmailAdapters: - SendgridEmailAdapter to send email messages via Sendgrid - SendmailEmailAdapter to send email messages via Sendmail - SMTPEmailAdapter to send email messages via SMTP

Flask-User works with the SMTPEmailAdapter by default, but another EmailAdapter can be configured like so:

# Setup Flask-User
user_manager = UserManager(app, db, User)

# Customize Flask-User
from flask_user.email_adapters import SendgridEmailAdapter
user_manager.email_adapter = SendgridEmailAdapter(app)

Customizing Email messages

Flask-User currently offers the following types of email messages:

confirm_email     # Sent after a user submitted a registration form
                  # - Requires USER_ENABLE_EMAIL = True
                  # - Requires USER_ENABLE_CONFIRM_EMAIL = True

forgot_password   # Sent after a user submitted a forgot password form
                  # - Requires USER_ENABLE_EMAIL = True
                  # - Requires USER_ENABLE_FORGOT_PASSWORD = True

password_changed  # Sent after a user submitted a change password or reset password form
                  # - Requires USER_ENABLE_EMAIL = True
                  # - Requires USER_ENABLE_CHANGE_PASSWORD = True
                  # - Requires USER_SEND_PASSWORD_CHANGED_EMAIL = True

registered        # Sent to users after they submitted a registration form
                  # - Requires USER_ENABLE_EMAIL = True
                  # - Requires USER_ENABLE_CONFIRM_EMAIL = False
                  # - Requires USER_SEND_REGISTERED_EMAIL = True

username_changed  # Sent after a user submitted a change username form
                  # - Requires USER_ENABLE_EMAIL = True
                  # - Requires USER_ENABLE_CHANGE_USERNAME = True
                  # - Requires USER_SEND_USERNAME_CHANGED_EMAIL = True

Emails are constructed using three email template files, using the Jinja2 templating engine. The ‘registered’ email, for example, makes use of the following template files:

registered_subject.txt   # Subject line
registered_message.html  # Message in HTML format
registered_message.txt   # Message in Text format

Which, in turn, depend on the common base template files:

base_subject.txt
base_message.html
base_message.txt

The base templates are shared across all message types. Typically the base templates define the message design (the look-and-feel) while the message templates define the message content.

Customizing Email templates

Before we can customize any of the email templates, we’ll need to copy them from the Flask-User install directory to your application’s template directory.

Copying Email template files

  1. Determine the location of where the Flask-User package is installed:

    # In a python shell, type the following:
import os
import flask_user
print(os.path.dirname(flask_user.__file__))

# Prints something like:
# ~/.envs/my_app/lib/python3.6/site-packages/flask_user

  2. The examples below assume the following:

    flask_user dir: ~/.envs/my_app/lib/python3.6/site-packages/flask_user
app dir:        ~/dev/my_app

Adjust the examples below to your specific environment.

  1. Copy the template files, substituting your flask_user and your template directory accordingly:

    # IMPORTANT:
# If you've already worked on customizing form templates, you can (and must) skip this step,
# since you've already copied the email templates along with the form templates.

cp ~/.envs/my_app/lib/python2.7/site-packages/flask_user/templates/flask_user ~/dev/my_app/app/templates/.
cp ~/.envs/my_app/lib/python2.7/site-packages/flask_user/templates/flask_user_base.html ~/dev/my_app/app/templates/.

You should now have an app/template/flask_user directory:

ls -1 ~/dev/my_app/app/templates/flask_user/emails

Expected output:

base_message.html
base_message.txt
base_subject.txt
confirm_email_message.html
confirm_email_message.txt
confirm_email_subject.txt
    ...

Steps 1) through 3) only need to be performed once.

Editing Email template files

After you’ve copied the Email template files <CopyEmailTemplateFiles>, you can edit any HTML or TXT template file in your app/templates/flask_user/emails/ directory, and change it to your liking.

Flask-User makes the following template variables available to all email templates:

app_name      # The value of the USER_APP_NAME app config setting
email         # The user's email
user          # The user's User object
user_manager  # The UserManager object

The following email templates also receive the following template variables:

# confirm_email templates
confirm_email_link     # Confirm email link with confirm email token

# forgot_password templates
reset_password_link    # Reset password link with reset password token

# invite_user templates
accept_invitation_link # Accept invitation like with register token
invited_by_user        # The user that created this invitation

Here’s the default base_message.html implementation on github.

Here’s the default confirm_email_message.html implementation on github.

• Intro       • Settings       • Forms       • Emails       • Advanced