Email Notifications

Freeform allows you to send email notifications upon submittal of a form. They are global and can be reused for multiple forms, saving you time when you are managing many forms.

Be sure to configure the Email Alert feature. It allows you to automatically send an email notification alerting the email address(es) specified when an email notification cannot be delivered.

Email notifications may not work as expected when using Sendmail on your local dev environment. Check out our Mailtrap setup guide.

Need to use the submitter of the form as Reply-to email address in admin email notifications?

Types of Email Notifications

Freeform allows you to send email notifications 6 different ways (all of them each being able to have their own notification templates, etc):

Admin

Email notifications can be sent upon successful submit of the form to one or more admin email addresses.

To set up:

In the form builder, click on the Notifications tab. Then click the New button beside the Admin menu.

Choose an email notification template from the Notification Template setting. If you haven't created any yet, be sure to do so.

In the Recipients area, add any email address(es) you'd like to receive an email notification each time the form is submitted successfully. If you need to specify more than one email address, hit Enter and additional email inputs will appear.

Finished!

ConditionalProNew in 5.0+

Email notifications can be conditionally sent to one or more admin email addresses based on the contents and/or option selection of any Freeform field(s).

To set up:

In the form builder, click on the Notifications tab. Then click the New button beside the Conditional menu.

Choose an email notification template from the Notification Template setting. If you haven't created any yet, be sure to do so.

In the Recipients area, add any email address(es) you'd like to receive an email notification each time the form is submitted successfully when the following condition(s) are met. If you need to specify more than one email address, hit Enter and additional email inputs will appear.

In the Rules area, configure any conditional rules you'd like to be met in order for this email notification to be sent.

If you need more sets of conditional rules, just repeat the process again. You may have as many rule sets as you like.

Finished!

User Select
LitePro
Renamed & Improved for 5.0+

Email notifications can be sent to one or more pre-defined admin email addresses that are selected by the user filling out the form using any Dropdown, Checkbox, Checkboxes, Radios, Multi-Select field types. For example, you might have a Dropdown field that contains different departments for the user to address the email to.

Be sure to set up your option fields as usual, and do not set email addresses as their options. That part is done inside the Notifications tab.

To set up:

In the form builder, click on the Notifications tab. Then click the New button beside the User Select menu.

Choose any Dropdown, Checkbox, Checkboxes, Radios or Multi-Select field in the Target field setting.

Choose an email notification template from the Default Notification Template setting. If you haven't created any yet, be sure to do so.

If you wish to have an email address notified if NO options are chosen, you can set email address(es) in the Default Recipients setting. Otherwise, leave this setting blank.

In the Recipient Mapping area, add email address(es) for each corresponding option. If you need to specify more than one email address for an option, hit Enter and additional email inputs will appear.

You can also choose to specify a different email notification template for any or all options.

Email addresses will never be rendered in the front-end form.

Finished!

Email FieldsRevised for 5.0+

Email notifications can be sent to the user submitting the form as long as you're using the Email field type. This is often used to send an email confirmation for the user.

To set up:

In the form builder, click on the Notifications tab. Then click the New button beside the Email Fields menu.

Choose any Email field in the Target field setting. If you currently don't have any, please add one to your form layout. If you are using a regular Text field to hold the email address, please switch it to an Email field type first.

When the form submitter enters their email address in this field, Freeform will use that email address to send the email notification.

Choose an email notification template from the Notification Template setting. If you haven't created any yet, be sure to do so.

Finished!

User-Defined

You can enable "tell-a-friend" type forms by including additional Email fields in your form. This would then allow the submitter of the form to specify a friend's email address and have them receive an email notification as well. This essentially works the same way as Email Field notifications above.

This feature could potentially be abused by spammers.

To set up:

In the form builder, click on the Notifications tab. Then click the New button beside the Email Fields menu.

Choose any Email field in the Target field setting. If you currently don't have one, please add one to your form layout. If you are using a regular Text field to hold the email address, please switch it to an Email field type first.

Choose an email notification template from the Notification Template setting. If you haven't created any yet, be sure to do so.

Finished!

Template-based

Email notifications can be set up dynamically at template level using the dynamicNotification parameter in your template. This allows you to hard code values or dynamically pass a value from another element such as a Craft Entry.

To set up:

Be sure to have an email notification template ready before proceding.

In your regular Twig template where the form is located, add the following parameter to your Form query:

dynamicNotification: {
    recipients: "[email protected]",
    template: "my-template.twig"
}

For multiples, use the array brackets:

dynamicNotification: {
    recipients: ["[email protected]", "[email protected]"],
    template: "my-template.twig"
}

For Twig file based templates, specify the full file name including file extension, e.g. my-template.twig.
For Database entry based templates, specify the handle name, e.g. myTemplate.

Finished!

Managing Email Templates

Email notification templates are available to be stored as files, in the database, or both. You can choose which one is best for your site. These templates can be managed either from the Freeform control panel or manually adding/editing template files directly. In order to send file-based email notifications, a directory path must be set for Freeform to manage these templates, as they are stored as Twig-based files. Please see the Directory Path setting under Settings → Template Manager).

If adding a brand new email notification template inside the form builder, Freeform will respect the Default Email Template Creation Method setting and contain basic default content that should be checked and updated once finished building your form.

Template Options

When editing templates directly inside the control panel, Freeform will automatically handle the structure of the template file. If you're creating/editing template files directly, there should be a heading comment block of code for all configuration options that might look something like this:

{# subject: New submission from your {{ form.name }} form #}
{# fromEmail: {{ craft.app.projectConfig.get('email.fromEmail') }} #}
{# fromName: {{ craft.app.projectConfig.get('email.fromName') }} #}
{# replyToEmail: {{ email }} #}
{# replyToName: {{ firstName }} {{ lastName }} #}
{# cc: [email protected] #}
{# bcc: #}
{# includeAttachments: true #}
{# presetAssets: 42,67 #}
{# templateName: My Template Name #}
{# description: A description of what this template does. #}

Email Notification templates may contain the following options:

Name - a common name for the notification template to identify it easier.
Handle - the unique identifier for the notification template, used when in your regular templates when specifying a notification template.
Description - a description for the notification template to help identify what it's used for, etc.
Subject - the subject line for the email notification.
- May include any Freeform field variables (fieldName) as well as form.name.
From Email - the email address the email notification will appear from.
- May include any Freeform field variable (fieldName).
  Using a dynamic approach with variables like above could have your emails marked as spam. It would be better to use something general here and set these in the Reply-to Email and Reply-to Name settings instead.
  
  If you are using SMTP or a service that uses SMTP (like Sendgrid, etc), please make sure that the email address you have configured in the From Email setting for the email notification exactly matches what you have set in the Craft Email Settings area. If you wish to use the submitters email address as the "From" email, use the Reply-to Email setting instead.
  
  Need to use the submitter of the form as Reply-to email address in admin email notifications?
From Name - the email address the email notification will appear from.
- May include any Freeform field variables (fieldName), e.g.
```
{{ firstName }} {{ lastName }}
```
  Using a dynamic approach with variables like above could have your emails marked as spam. It would be better to use something general here and set these in the Reply-to Email and Reply-to Name settings instead.
Reply-to Email - the email address the email notification will have set for Reply-to.
- May include any Freeform field variable (fieldName).
- Leave blank to use the From Email value.
Reply-to Name - the name of the email/sender the email notification will have set for Reply-to.
- May include any Freeform field variable (fieldName).
- Leave blank to use the From Name value.
CC - the email address the email notification will also send to as CC.
- May include any Freeform field variable (fieldName).
- Separate multiples with a comma.
- Leave blank to not use CC.
BCC - the email address the email notification will also send to as BCC.
- May include any Freeform field variable (fieldName).
- Separate multiples with a comma.
- Leave blank to not use BCC.
Include Attachments - include uploaded files as attachments in email notification.
Predefined Assets Pro - select any Assets you wish to include as attachments on all email notifications using this template.
- Useful if you wish to include a PDF ticket or instructions document to submitter email notifictions, etc.
- Can also preparse Twig, allowing you to dynamically attach an asset to the email notification based on a user's selection, etc.
Auto 'Text-Only' version - when enabled, Freeform will automatically provide a Text-only version of the notification based on the HTML version. If disabled, a Text-Only Body setting will display for manually handling this.
Email Body (HTML) - the HTML body of the email notification to be sent.
- A Plain Text email notification option is also available.
  - To use HTML only, leave the Plain Text field empty. To use Plain Text only, leave the HTML field empty. To use HTML with a Plain Text fallback, use both.
- May include any Freeform field variable (fieldName) as well as form.name, form.id, form.handle and dateCreated.
  - Available field options:
    - fieldName.label - displays the label (name) of the field.
    - fieldName or fieldName.value or fieldName.valueAsString - displays the data submitted. Revised for 5.0+
      - Example: apples
      - Array of data example: apples, oranges
    - fieldName.labels or fieldName.labelsAsString - displays the option label(s) submitted (for fields with options). New in 5.0+
      - Example: Apples
      - Array of data example: Apples, Oranges
        Avoid using fieldName.value or fieldName.labels, as it may not be a string and could trigger an error.
    - fieldName.instructions - displays the instructions for the field.
    - fieldName.handle - displays the handle of the field.
    - fieldName.placeholder - displays the placeholder of the field.
- May also use allFields or allFieldsAndBlocks variables to automate parsing of fields.
  - allFieldsAndBlocks works like allFields, but includes HTML and Rich Text blocks.
    - To benefit from inclusion of HTML and Rich Text blocks correctly rendering HTML, you'll need to use a conditional inside the loop and add the |raw filter to field.value. See example below.
  - Available options:
    - field.label - displays the label (name) of the field.
    - field.valueAsString - displays the option value(s) submitted. Revised for 5.0+
      - Example: apples
      - Array of data example: apples, oranges
    - field.labelsAsString - displays the option label(s) submitted (for fields with options). New in 5.0+
      - Example: Apples
      - Array of data example: Apples, Oranges
        Avoid using field.value or field.labels, as it may not be a string and could trigger an error.
    - field.instructions - displays the instructions for the field.
    - field.handle - displays the handle of the field.
    - field.placeholder - displays the placeholder of the field.
  - To parse only fields with data, you can use:
    {% for field in allFields if field.valueAsString %}
  - Excludes File Upload fields. To render these manually, see example here.
  - Excludes Email Marketing (mailing list checkbox) selection. To render manually, see example here.
  - Excludes Signature fields. To render manually, use:
    <img src="{{ submission.myFieldHandle.value }}" alt="Signature" />
- You may iterate over submission values from the Submission object (as long as you're storing submitted data)
- If using the Elements integration, you may use the element object to display data from the newly created Craft Element such as ID, title, username, etc.
  - For example (but not limited to):
    - element.id will return the ID of the newly created Element
    - element.title will return the title of the newly created Craft Entry
    - element.username will return the username of the newly created Craft User
  - If you have more than 1 element integration for the form, you can use either:
    {% for item in element %} {{ element[0].id }}, {{ element[1].id }}, etc
Email Body (Text) - the Plain Text body of the email notification to be sent.
- All of the variables listed above for Email Body (HTML) are available here as well.
- To use HTML only, leave the Plain Text field empty. To use Plain Text only, leave the HTML field empty. To use HTML with a Plain Text fallback, use both.
- When making templates directly (outside of the control panel), simply wrap an additional set of email body contents with {# text #} {# /text #} in your notification template. See example below.

Examples

Basic Automated Email Body

Below is a basic automated example for the Email Body setting:

<p>The following submission came in on {{ dateCreated|date('l, F j, Y \\a\\t g:ia') }}.</p>
<ul>
{% for field in allFields %}
    <li>
        {{ field.label }}:
        {% if field.implements('options') %}
            {{ field.labelsAsString }}
        {% else %}
            {{ field.valueAsString }}
        {% endif %}
    </li>
{% endfor %}
</ul>

Manual Email Body

Below is a manually built example for the Email Body setting:

<p>The following submission came in on {{ dateCreated|date('l, F j, Y \\a\\t g:ia') }}.</p>
<p>Here are the details:</p>
<ul>
    <li>Name: {{ firstName }} {{ lastName }}</li>
    <li>Email: {{ email }}</li>
    <li>Home Phone: {{ homePhone }}</li>
    {% if cellPhone|length %}
        <li>Cell Phone: {{ cellPhone }}</li>
    {% endif %}
    <li>
        Services interested in:
        <ul>
        {% for value in interestedIn.value %}
            <li>{{ value }}</li>
        {% endfor %}
        </ul>
    </li>
    <li>
        Message:<br />
        {{ message|nl2br }}
    </li>
</ul>

Basic Notification Template File

Below is what a basic template might look like when editing notification template files directly (outside of the CP):

{# subject: New submission from your {{ form.name }} form #}
{# fromEmail: {{ craft.app.projectConfig.get('email.fromEmail') }} #}
{# fromName: {{ craft.app.projectConfig.get('email.fromName') }} #}
{# replyToEmail: {{ email }} #}
{# includeAttachments: true #}
{# templateName: My Template Name #}
{# description: A description of what this template does. #}

<h2>New submission on your {{ form.name }} form</h2>

<p>The following submission came in on {{ dateCreated|date('l, F j, Y \\a\\t g:ia') }}.</p>
<ul>
{% for field in allFields %}
    <li>
        {{ field.label }}:
        {% if field.implements('options') %}
            {{ field.labelsAsString }}
        {% else %}
            {{ field.valueAsString }}
        {% endif %}
    </li>
{% endfor %}
</ul>

Include a Text-only version

When wanting to add a text-only version of the Email Body when editing notification template files directly (outside of the CP), wrap an additional set of email body contents with {# text #} {# /text #}:

{# subject: New submission from your {{ form.name }} form #}
{# fromEmail: {{ craft.app.projectConfig.get('email.fromEmail') }} #}
{# fromName: {{ craft.app.projectConfig.get('email.fromName') }} #}
{# replyToEmail: {{ email }} #}
{# includeAttachments: true #}
{# templateName: My Template Name #}
{# description: A description of what this template does. #}

<h2>New submission on your {{ form.name }} form</h2>

<p>The following submission came in on {{ dateCreated|date('l, F j, Y \\a\\t g:ia') }}.</p>
<ul>
{% for field in allFields %}
    <li>
        {{ field.label }}:
        {% if field.implements('options') %}
            {{ field.labelsAsString }}
        {% else %}
            {{ field.valueAsString }}
        {% endif %}
    </li>
{% endfor %}
</ul>

{# text #}
The following submission came in on {{ dateCreated|date('l, F j, Y \\a\\t g:ia') }}

{% for field in allFields %}
- {{ field.label }}: {% if field.implements('options') -%}
        {{- field.labelsAsString }}
    {%- else -%}
        {{- field.valueAsString }}
{% endif %}
{% endfor %}
{# /text #}

Only Parse Fields with Data

To only parse fields that include data submitted with them, you would add the following conditional:

<p>The following submission came in on {{ dateCreated|date('l, F j, Y \\a\\t g:ia') }}.</p>
<p>Here are the details:</p>
<ul>
{% for field in allFields if field.valueAsString %}
    <li>{{ field.label }}: {{ field.valueAsString }}</li>
{% endfor %}
</ul>

Include HTML and Rich Text Blocks

If you wish to include HTML and Rich Text blocks in the output, use the allFieldsAndBlocks variable instead of allFields. You'll need to perform the additional step of using a conditional to sniff out these fields and apply the |raw filter:

<p>The following submission came in on {{ dateCreated|date('l, F j, Y \\a\\t g:ia') }}.</p>
<p>Here are the details:</p>
{% for field in allFieldsAndBlocks %}
   {% if field.type == "html" or field.type == "rich-text" %}
      {{ field.value|raw }}
   {% else %}
       <p>{{ field.label }}: {{ field.valueAsString }}</p>
   {% endif %}
{% endfor %}

Using Submission object

You may also have your notification email template code iterate over submission values from the Submission object (as long as you're storing submitted data) like this:

{% if submission is not null %}
    <h4>{{ submission.id }}: {{ submission.title }}</h4>
    <ul>
    {% for field in submission %}
        <li>{{ field.label }}: {{ attribute(submission, field.handle) }}</li>
    {% endfor %}
    </ul>
{% endif %}

Using Layouts

You may also use another template to set a layout for your email notification templates, making it easier to set consistent headings, footers and styles globally across all of your Email Notification templates. Like anywhere else, just make use of {% extends "some/template" %}.

Create a layout template anywhere in your Craft Templates directory (e.g. _layout/email-notifications):

Please note that any additional template files (e.g. _layout.twig, _footer.html, etc) must NOT be stored inside of the Email Notification Templates directory, as Freeform expects that every file in here is a complete email notification template and will choke on any additional files.

<html>
<head>
    <title>Global Layout</title>
</head>
<body>

<h1>Global Layout</h1>
<div>
    {% block content %}{% endblock %}
</div>

</body>
</html>

And then in your Freeform email notification template, something like:

{% extends "_layout/email-notifications" %}

{% block content %}

    <p>Submitted on: {{ dateCreated|date('l, F j, Y \\a\\t g:ia') }}</p>
    <ul>
        {% for field in allFields %}
            <li>{{ field.label }}: {{ field.valueAsString }}</li>
        {% endfor %}
    </ul>

{% endblock %}

Including File Upload Data

File Upload field data is excluded from automated rendering in allFields variable. You may of course include files as attachments, but if you wish to include an uploaded image rendered into the notification or just show a URL link to the file uploaded, you can do that by retrieving the Asset ID from the Submission object, and then using the Assets query:

<p>The following submission came in on {{ dateCreated|date('l, F j, Y \\a\\t g:ia') }}.</p>
<p>Here are the details:</p>
<ul>
{% for field in allFields %}
    <li>{{ field.label }}: {{ field.valueAsString }}</li>
{% endfor %}
</ul>

{% set assetId = submission.uploadFieldHandle.value %}
<p>Here's the uploaded file URL(s):</p>
<ul>
    {% for asset in craft.assets.id(assetId).all %}
        <li>{{ asset.url }}</li>
    {% endfor %}
</ul>

Passing Freeform data to another Template Query

If you need to pass a Freeform field value (such as an ID) into another Craft query like craft.entries or craft.users in email notification templates or elsewhere, be sure to specify the Freeform field as myFreeformFieldHandle.value. So for example:

{{ craft.users.id(myFFfieldHandle.value).one().name }}

{% set item = craft.entries.section('section').id(myFFfieldHandle.value).one %}

Show textarea line breaks in Email Notifications

Textarea data is stored in the database as newlines, which obviously don't parse as line breaks when trying to display in email notifications or on front end with Submissions object. To make this happen, use the nl2br Twig filter:

{{ coverLetter|nl2br }}

Need to display linebreaks for Textarea fields in email notifications or on the front end with a Submissions query?

Extra Notifications

Freeform allows you to send extra email notifications for any reason.

Resending Email NotificationsPro

If you ever run into any issues where email notifications did not send correctly (whether it be that there was an issue with Freeform, your templates, your email server, etc), Freeform allows you to effortlessly have email notifications resent. Simply select the affected submissions from the CP Submissions list page, and then click the cog (gears) icon at the bottom left and select Resend Notifications. Freeform will then resend the email notifications for you.

Send Additional NotificationPro

If you ever need to send additional notifications to other email addresses for any reason at any time, you can use the Send Additional Notification feature. This is an email notification that is independent of other notifications, so it may use a different email notification template and contain different wording or data, etc.

Simply select the applicable submission(s) from the CP Submissions list page, and then click the cog (gears) icon at bottom right and select Send Additional Notification. Freeform will then present you with a modal that allows you to select an email notification template and specify email address (es) to notify.

Email Notifications

Types of Email Notifications​

Admin​

ConditionalProNew in 5.0+​

User SelectLiteProRenamed & Improved for 5.0+​

Email FieldsRevised for 5.0+​

User-Defined​

Template-based​

Managing Email Templates​

Template Options​

Examples​

Basic Automated Email Body​

Manual Email Body​

Basic Notification Template File​

Include a Text-only version​

Only Parse Fields with Data​

Include HTML and Rich Text Blocks​

Using Submission object​

Using Layouts​

Including File Upload Data​

Passing Freeform data to another Template Query​

Show textarea line breaks in Email Notifications​

Extra Notifications​

Resending Email NotificationsPro​

Send Additional NotificationPro​

Types of Email Notifications

Admin

ConditionalProNew in 5.0+

User Select
LitePro
Renamed & Improved for 5.0+

Email FieldsRevised for 5.0+

User-Defined

Template-based

Managing Email Templates

Template Options

Examples

Basic Automated Email Body

Manual Email Body

Basic Notification Template File

Include a Text-only version

Only Parse Fields with Data

Include HTML and Rich Text Blocks

Using Submission object

Using Layouts

Including File Upload Data

Passing Freeform data to another Template Query

Show textarea line breaks in Email Notifications

Extra Notifications

Resending Email NotificationsPro

Send Additional NotificationPro