Freeform Documentation

Learn the basics, and get to know Freeform inside and out.

Freeform 1.x Docs

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 5 different ways (all of them each being able to have their own notification templates, etc):

Admin Notifications #

Email notifications can be sent to one or more admin email addresses. To setup:

  1. In Composer interface for the form, click on the Admin Notifications (envelope icon) tab at the top right.
  2. Select and/or add an email template.
  3. Specify admin email address(es) in the text area below. Separated multiples by line breaks only.

Dynamic Recipients #

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 the Dynamic Recipients field. For example, you might have a select dropdown field that contains different departments for the user to address the email to. To setup:

  1. In Field Editor (Freeform -> Fields) or Composer Quick Field (Add New Field button at left), create a new field of the Dynamic Recipient field type.
  2. In Composer interface for the form, drag that field into field layout.
  3. Click on field inside field layout and look over to the Property Editor (right column).
  4. Select and/or add an email template.
  5. Choose how you wish to display the field (Select, Radios, Checkboxes).
  6. Specify email addresses (and corresponding labels) for each option you wish to make available for users to select.
    • You can specify more than 1 email address per option - just separate multiples with comma (, no space).
    • Email addresses will NOT be rendered in the front end form, but rather a corresponding ID value will show up.

NOTE: You currently cannot specify more than 1 option with the same email address. It will appear to display somewhat correctly, but you'll notice some odd behaviors when the user submits the form. The only workaround for this currently is to create email address aliases for each duplicate option.

Dynamic Template Notifications #

Email notifications can be setup 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 setup:

  1. In your Twig template, add the following parameter to your freeform.form function: dynamicNotification: { recipients: ["admin@example.com", "support@example.com"], template: "test.html" }
  • For Database entry based templates, specify the handle for template.
  • For Twig file based templates, specify the full file name including .html for template.

NOTE: This feature uses Session data. It will likely not work properly if the page is cached with something like Varnish, etc.

User/Submitter Notifications #

Email notifications can be sent to the user submitting the form using the Email field type. This is often used to send an email confirmation for the user. To setup:

  1. In Field Editor (Freeform -> Fields) or Composer Quick Field (Add New Field button at left), create a new field of the Email field type.
  2. In Composer interface for the form, drag that field into field layout.
  3. Click on field inside field layout and look over to the Property Editor (right column).
  4. Select and/or add an email template.

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

User Defined #

Email notifications can be sent to email addresses of the submitters choosing using the Email field type. This would be commonly used for "tell-a-friend" type forms, or forms to send out any other type of invites. The user submitting the form would enter email address(es) in the form and Freeform can send an email notification to them. This essentially works the same way as User/Submitter Notifications. Just be careful as this could be abused by spammers. To setup:

  1. In Field Editor (Freeform -> Fields) or Composer Quick Field (Add New Field button at left), create a new field of the Email field type.
  2. In Composer interface for the form, drag that field into field layout.
  3. Click on field inside field layout and look over to the Property Editor (right column).
  4. Select and/or add an email template.

To allow sending of email notifications to more than 1 email address (e.g. in the case of a "tell-a-friend" type form), you will need to add multiple input fields, each with the input name email[]. This approach would require that you code this part manually however.

NOTE: This feature could be abused by spammers.

Overview of Email Notification Template Options #

Email Notifications List

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

Create an Email Notification

Database templates are managed within the Craft control panel in the Email Notifications page in Freeform (Freeform > Email Notifications). Email Notification templates 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.
      • 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.getValueAsString() }}</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).first().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 %}

Resending Email Notifications #

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 top left and select Resend Notifications. Freeform will then resend the email notifications for you.

Resend Email Notifications