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.

Assigning Notifications to Fields/Forms

Email notifications can be sent to email address(es) specified for admins (in the Notify section of Composer (right column)) as well as email addresses specified/selected in the Email and Dynamic Recipients field types. To assign an email notification template to these fields, click on the field in Composer, and then in the Property Editor (right column), select a notification template you want used to generate an email notification for the entered/selected email address. Email notifications can even be done dynamically at template level.

Overview of Email Notification Template Options

Email notification templates can be managed 2 different ways:

1. As database entries within the Craft control panel in the Email Notifications page in Freeform (Freeform > Email Notifications).
2. As HTML template files within the Craft Templates directory.

In addition to this, email notification templates can be created directly at form level within Composer. Email templates created this way are subject to the Default Email Notification Creation Method preference in Freeform settings. Email notification templates that are created within Composer will contain basic default content and should be checked and updated once finished building your form.

Managing Email Templates within Craft CP (Database)

• 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.
    • Can include any Freeform field variables ({{ fieldName }}) as well as {{ form.name }}.
• From Email #
  • The email address the email notification will appear from.
    • Can include any Freeform field variable ({{ fieldName }}).
      • NOTE: Using dynamic approach with a variable could have your emails marked as spam.
• From Name #
  • The email address the email notification will appear from.
    • Can include any Freeform field variables ({{ fieldName }}).
      • Ex: {{ firstName }} {{ lastName }}
      • NOTE: Using dynamic approach with variables could have your emails marked as spam.
• Reply-to Email #
  • The email address the email notification will has set for Reply-to.
    • Can include any Freeform field variable ({{ fieldName }}).
      • NOTE: Using dynamic approach with a variable could have your emails marked as spam.
    • Leave blank to use the From Email address.
• Include Attachments #
  • Include uploaded files as attachments in email notification.
• Email Body #
  • The HTML body of the email notification to be sent.
    • Can 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 }} - displays the data submitted.
          • Example: Apples
          • Array of data example: Apples, Oranges
        • {{ fieldName.instructions }} - displays the instructions for the field.
        • {{ fieldName.handle }} - displays the handle of the field.
        • {{ fieldName.placeholder }} - displays the placeholder of the field.
    • Can also use allFields variable to automate parsing of fields. #
      • Available options:
        • {{ field.label }} - displays the label (name) of the field.
        • {{ field.valueAsString }} - displays the option label(s) submitted.
          • Example: Apples
          • Array of data example: Apples, Oranges
        • {{ field.getValueAsString(false) }} - displays the option value(s) submitted.
          • Example: apples
          • Array of data example: apples, oranges
          • Avoid using {{ field.value }}, 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, use {% for field in allFields if field.valueAsString %}
      • Excludes File Upload fields. To render these manually, see example here.
      • Excludes Mailing List selection. To render manually, see example here.
    • Can iterate over submission values from the Submission object(as long as you're [storing submitted data)

Managing Email Templates as HTML Files

HTML template files have the same options as Database templates, but since all of the content is stored within a template (and nothing in the database), these template files will have a heading comment block of code with configuration options.

To clarify, your template code would look no different than how it does for Database template method, except you'd have a comment block at the top of the template with config options like this:

{# subject: New submission from your {{ form.name }} form #}
{# fromEmail: {{ craft.app.systemSettings.getSettings('email').fromEmail }} #}
{# fromName: {{ craft.app.systemSettings.getSettings('email').fromName }} #}
{# replyToEmail: {{ craft.app.systemSettings.getSettings('email').fromEmail }} #}
{# includeAttachments: true #}
{# description: A description of what this template does. #}

That is the default set of config data, but you can of course adjust it to whatever you like.

Examples

Below is a basic automated example for database method:

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

And here is the same example but for HTML file method:

{# subject: New submission from your {{ form.name }} form #}
{# fromEmail: {{ craft.app.systemSettings.getSettings('email').fromEmail }} #}
{# fromName: {{ craft.app.systemSettings.getSettings('email').fromName }} #}
{# replyToEmail: {{ craft.app.systemSettings.getSettings('email').fromEmail }} #}
{# includeAttachments: true #}
{# description: A description of what this template does. #}

<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 }}: {{ field.valueAsString }}</li>
  {% endfor %}
</ul>

Below is a manually built example for database method:

<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>Email: {{ email }}
  <li>Home Phone: {{ homePhone }}
  <li>Cell Phone: {{ cellPhone }}
  <li>
    Services interested in:
    <ul>
    {% for value in interestedIn.value %}
      <li>{{ value }}</li>
    {% endfor %}
    </ul>
  </li>
  <li>
    Message:<br />
    {{ message }}
  </li>
</ul>

You can 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.fieldMetadata %}
    <li>{{ field.label }}: {{ attribute(submission, field.handle) }}</li>
  {% endfor %}
  </ul>
{% endif %}

Including File Upload Data

File Upload field data is excluded from automated rendering in allFields variable. You can 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 function:

<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 %}
<p>
  Here's the uploaded file URL:
  {{ craft.assets.id(assetId).one().url }}
</p>

Including Mailing List Selection Data

Mailing List checkbox selections are excluded from automated rendering in allFields variable. Since they are special fields and not part of the regular fields, this data isn't available in the control panel or Submission object, etc. However, you can access the user's selection via the Form object (and specify the hash available in the Handle area of the Property Editor for the Mailing List field inside Composer). The example below will render as 1 if the user checked the checkbox:

{{ form.get("BmLxw1ONn").value }}

This could be used as a conditional like this:

{% if form.get("BmLxw1ONn").value == 1 %}
  Opted into mailing list.
{% else %}
  Did NOT Opt into mailing list.
{% endif %}