Email & Templates Overview

    Overview

    This section is designed to review how to utilize email, email templates, and messenger templates in FusionAuth. See Email APIs for additional information on integrating directly with the email APIs and Messenger Templates for more information on modifying messenger templates directly.

    Email

    Email and Email Templates are a core feature of FusionAuth. This feature provides the ability to communicate with your Users via email. FusionAuth comes shipped with a few basic email templates for common workflows such as Setup Password, Change Password and Verify Email.

    In order to use email templates and email based workflows, you will need to enable and complete the SMTP configuration. Generally this will have been completed during the FusionAuth Setup Wizard. If you have not yet completed this step see the topic link below for configuring email.

    Here are the topics in this section:

    Here’s a brief video covering some aspects of email templates:

    Message Templates

    Message templates are used by Messengers. Currently there is only one messenger type: SMS. Just as with emails, these can be customized and localized, but unlike email templates, there are not HTML and text versions of a messenger template.

    Here are the topics in this section:

    Troubleshooting

    FusionAuth sends a lot of email, for forgotten passwords, passwordless login and other features.

    Troubleshooting email delivery is difficult. There are many factors affecting it. However, there are steps you can take to narrow down the problem.

    Send A Test Email

    The Send Test Email button has been available since 1.16.0

    The first step is to ensure that you can send a test email. Navigate to Tenants → Your Tenant → Edit → Email and send a test email. If it is received, FusionAuth can send emails via SMTP.

    Sending a test email

    If sending a test email fails, a tool such as SWAKS can help debug SMTP issues. Using this tool removes FusionAuth from the equation.

    Further Investigation

    If the test email succeeds, but you aren’t receiving other emails, investigate further by following these steps:

    • Send emails to different addresses at different providers and check the spam folder.

    • Make sure that you are firing the event that you expect to send email correctly. For instance, if you are looking for email verification of users, make sure that is enabled.

    • Test with a different FusionAuth function. Sending a password reset email is easy to do from the user details screen.

    • Make sure the email template is correct, or use a default template.

    Additionally, confirm that the template content matches up with the template type. Otherwise template variables will be missing. If this occurs, you may see a message like this in the Event Log. 

    
Render Errors
---------------
html : freemarker.core.InvalidReferenceException: The following has evaluated to null or missing:
==> changePasswordId  [in nameless template at line 5, column 59]

    SMTP Logging

    To enable SMTP logging prior to 1.37.0 follow these steps:

    1. Enable debugging by navigating to Tenants → Your Tenant → Edit → Advanced → SMTP Settings → Additional properties and add mail.debug=true.

    2. Save the tenant.

    3. Send an email.

    4. View the system logs by navigating to System → Logs.

    5. Select fusionauth-app.log and you will see verbose SMTP output.

    To enable SMTP logging for version 1.37.0 or later follow these steps:

    1. Enable debugging by navigating to [breadcrumb]#Tenants → Your Tenant → Edit → Email → Debug.

    2. Save the tenant.

    3. Send an email.

    4. View the Event Logs by navigating to System → Event Logs.

    5. Select the Event Log that starts with "Email debug information".

    Doing this logs the full SMTP conversation, which can be verbose. You should remove this setting when you have finished troubleshooting.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.