Freeform for Craft

5.x ✓ Latest

• 5.x✓ Latest
• 4.x
• 3.xRetired
• 2.xRetired
• 1.xRetired

Plugin Store

Forms & Fields

# 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.

# 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
• Conditional Pro
• User Select
  LitePro
• Email Fields
• User-Defined
• Template-based

# Admin

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

To set up:

# Conditional ProNew 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:

# 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.

To set up:

# Email Fields Revised 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:

# 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.

To set up:

# 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:

dynamicNotification: {
    recipients: "admin@example.com",
    template: "my-template.twig"
}

dynamicNotification: {
    recipients: ["admin@example.com", "support@example.com"],
    template: "my-template.twig"
}

# 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: ring@my-precio.us #}
{# 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).

    WARNING

    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.

    TIP

    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.

    User Guide:

    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 }}
    

    1
    

    WARNING

    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

        TIP

        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

        TIP

        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 %}
      

      1
      
    • 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" />
      

      1
      
  • 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
      

      1
      2
      
• 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):

<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 }}

OR

{% 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 }}

# Extra Notifications

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

# Resending Email Notifications Pro

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 Notification Pro

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.