Sending Email

Using the Send Email form handler to send email messages on form submission.

To send one or more emails on form submission, use the Send Email form handler. As a prerequisite, you also need to configure your Concrete CMS site to send email. If you anticipate any more than a trivial traffic volume, this should be an External SMTP Server. See DashboardSystem & Settings > Email > SMTP Method.

The Send Email form handler

To send an email when a form is submitted, you can insert a Send Email form handler into the submit pipeline. This handler provides a proforma for the email. You can build the boilerplate for an email using {{place_holders}} to be filled with system or entered form values. All fields in the Send Email handler configuration dialogue can process {{place_holders}}.​​

We also have an example you can test to send yourself an email from a form.

Condition

An optional condition can be used to control sending of an email.

Sender

The sender section allows configuration of From and Reply To email addresses. This is similar to configuring any email client. If left empty, both will default to your site configured email.default.address and email.default.name.

Recipients

The recipients section is a growing list. Every email needs at least one recipient and after that, you can add as many TO, CC or BCC addresses as you like. This is not designed for bulk email (see later). This is a form response, not a mailing list system.

Example

In our example below we have

  1. A directly entered email address for the From field.
  2. A user ID [1] for the Reply To field - this is just to show you what can be done. Normally Reply To would be the same as From !
  3. A Recipient {{email}} field submitted with the form.
  4. A directly entered recipient address as a CC.

These varied settings are purely to illustrate the capabilities. A real form will be more sensible!

The Message

The message part of an email is similar to configuring any message with Form Reform. You can combine text and {{place_holders}} to customize a boilerplate email with fields from the form and other data values.

The main thing to remember is that any rich text (HTML) email must be self contained. It will not have the benefit of CSS classes provided by your web site theme. Hence anything beyond basic HTML tags will need some hand crafted style="" attributes.

With that in mind, we have a third option for how the body is formatted, so that any images within the body are base 64 encoded and embedded into the email.

Inserting Images

HTML formatted emails can be sent with images.

With the HTML option, The images are not actually sent with the email, just a url to the image on your web server. With the HTML with embedded images option, images are base 64 encoded inline and become part of the actual message body.

Apart from how images are sent as a URL or embedded, everything else is the same. In its basic form, just use the image tool in the rich text editor to pick an image from the file manager and add the <img> tag into the message body.

To use an image uploaded with a form, we need to create an image tag containing a {{place:holder}} for the image URL or fid. The simplest way to do this is to add any image to create the <img> tag, then enter the [<>] source view of the rich text editor and modify the content of the <img> tag.

For example, with a Webcam input called 'mugshot', an image can be modified like:

<p><img alt="My Mugshot" src="{{webcam_fid:mugshot}}" /></p>

Once a file has been imported from quarantine and mapped to an fID with an uploader input called 'my_file', the input 'my_file' will now be the fID of the file. In this case an image can be modified like:

<p><img alt="My File" src="{{form:my_file}}" /></p>

With the HTML option, when the email is sent the {{webcam_fid:mugshot}} placeholder is expanded to the URL for the mugshot on your web server. Similarly the placeholder {{form:my_file}} is expanded to the URL of that file on your web server.

With the HTML with embedded images option,the {{webcam_fid:mugshot}} or {{form:my_file}} placeholders are expanded to a base 64 encoded copy of the image.

When the email is received, the recipient's mail client will display the image in the formatted email.

HTML

  • Images are not sent with the email.
  • The email sources images directly from the web server when the email is viewed.
  • Email's are smaller because images are not embedded.
  • If an image is deleted from the web server, the email will no longer display the image.

HTML with embedded images

  • Images are encoded in to the email body.
  • No further reference is made to the web server.
  • Emails are bigger because they contain the images.
  • If an image is deleted from the web server, the email will continue to display.

This last point of HTML with embedded images introduces a further possibility. Rather than importing an image to the file manager using the Import Quarantine Files handler, a quarantined file can be embedded directly into an email.

<p><img alt="My Mugshot" src="{{quarantine:mugshot}}" /></p>

If you only ever need an uploaded file to be part of an email, this can be a big advantage for both saving server space and GDPR because the file is not kept on the server.

This would not work with the HTML option, because the URL inserted would no longer be valid as soon as the quarantined file was cleared.

Attaching files and images

Attaching a file or image is a completely different mechanism to inserting images into the body of an email. In this case, the file is sent with the email as an attachment, hence will never need to refer back to a URL on the web server. The attachment is a frozen copy of the file at the time the email is sent.

Attachments can be any kind of file, including images.

The Attach Files section of the Send Email handler configuration has two means of configuring attachments that can be used individually or together.

  • Choose from the File Manager
    • None
    • Individual file - just one file
    • Fileset - all files in a fileset
    • Folder - all files in a folder
  • List of fID - typically used with a placeholder such as {{webcam_fid:mugshot}} or {{quarantine:mugshot}} to attach files uploaded with a form to the email.

In all cases it is the file that is attached, not a specific thumbnail, so it is up to you to make sure any file that could be attached to an email or embedded in an email is appropriately sized.

Do not send

Our final option is a checkbox to not send an email. This will do everything connected with building an email, except that sending will be disabled. This can be useful when developing and testing a form. But please remember to actually enable the sending when you have finished testing!

Email address validation

The default validation for all email addresses is:

  • Strict - the email has to conform strictly to email address specifications.
  • Test MX - the email domain is cross-checked against registered domains.

Validation is applied to any address that can be fixed at the time the edit dialogue is saved and again before an email is sent.

If your web server has the php function checkdnsrr() disabled, testing the MX record could be both extremely slow and always fail. Or it could even end in a server error. In such cases you may want to disable Test MX Record

email validation config optionsIn form handlers these settings are global. Configure them in one Send Email form handler and the same settings are applied across all Send Email form handlers.

These settings can also be edited manually in /application/config at jl_form_reform.email.validation.

A further setting which is configuration file only is jl_form_reform.email.validation.minimal. When true, this will skip the entire core validator class and use basic php validation for the email address. The other flags would then be ignored. When set, this flag also overrides the validation settings for Email and Email Confirm input blocks.

Email input validationIn the form input blocks for Email and Email Confirm, similar settings are specific to just that form input. Thus email validation could be configured to Test MX for user entered email addresses when the form input is validated, but not checked so rigorously when the email is sent. This would be a fair optimization to configure and gain a few milliseconds on overall form processing time.

Multiple Emails

Multiple Recipients

To send an email to multiple recipients, simply add them to the list of recipients in a single Send Email form handler.

The Recipient section is an extending list that can be added to and dragged into sequence.

Multiple Messages

To send different emails to different recipients, you can add more than one Send Email handler to the form handler pipeline, each with its own configuration.

You can also use a Condition If handler section to send different emails depending on form processing.

Bulk Email

The Send Email handler is not designed to manage mailing lists and bulk email. Any kind of bulk email will require subscriber management and unsubscribe processing as a legal necessity in most countries. If you need to manage bulk email, consider using a mailing list service.

If you require a form to connect to a bulk email service, consider developing a specialized form handler plugin for Form Reform

SMTP Server connection

As noted above, the default php mail functionality is not designed form anything beyond trivial use. On many web servers it may be disabled. Many recipient servers will bounce email sent by php mail or flag it as spam. Hence if you are using the Form Reform Send Email handler, you should also consider configuring your site to use an external SMTP mail server.

This can be configured at DashboardSystem & Settings > Email > SMTP Method. More details are available in the Concrete CMS Documentation

In your SMTP account, the address in the From field must be configured as an allowed sender. The most likely reason for an email to fail is that your SMTP account is not configured to send from this address.

Additional Pages

Reform the way you add new input controls

If you need a specialized template or a custom input element, you can design new templates  or new block types for form elements as you would any block type.

Blocks are easy for third party addition or extension. Block templates and are the first thing any Concrete CMS developer learns to code. They are one of the easiest things to code. The underlying mechanisms are well established and reliable.

Reform what you can do with form data

Form handlers are built about the same extensible plugin system as many of my other addons (Universal Content Puller, Omni Gallery, Extreme Clean ...).

The whole system is aimed at easy extension within Form Reform, by third party addons, by agencies and by site building developers.

Handlers can be easily added to do whatever you want with the form data.

Reform where you can save form data

Saving form data with Form Reform is simply a handler in the processing pipeline. You can save to multiple locations or just one location.

If you need to save data elsewhere, such as to a dedicated table, a table provided through another addon, to another database, send it to an API, forward it to another server, or anywhere you can imagine, you can adapt or develop a form handler to do so.

The complexity of the code depends on where you are saving or sending the data, but wrapping that into a form handler plugin for Form Reform is straight forward.

The Form Reform handler plugin system is designed for easy extension.

Form Reform

Reform the way forms are built. Build a form out of blocks. Take control of how form submissions are processed and how the submitted data is stored. Easy to extend. Easy to reconfigure. Tangible data. Easy to add your own integrations.

Form Reform Display

List and display form submissions from Form Reform.

Form Reform UTM

Not just Form Reform and not just UTM! Capture and hold incoming UTM (or other) tags and make the tag values available to Form Reform and/or Conditional Redirect as {{place_holders}}. You don't need Form Reform to use this.

Form Reform Dynamics

Form handlers for querying Microsoft Dynamics, forwarding and updating form data to Microsoft Dynamics.

Snapshot

A suite of advanced image capture and upload tools. Enhanced drag and drop file uploading. Make screengrabs from within Concrete CMS. Capture images directly from device webcams. Edit images before uploading.

Form Reform Attributes, Express and Users

Save submitted forms to Express objects and user attributes. Add and remove users from groups.

Form Reform Image Picker

Form Reform Image Picker provides an image picking input block for Form Reform. The Image Picker Input is preconfigured to connect to most Omni Gallery gallery and slider display widgets, the core gallery block, and thumbnail showing templates for the core page list block. Advanced settings allow the Image Picker Input to be configured to pick images from other galleries and sliders.

Form Reform Data Picker

Form Reform Data Picker provides data picking input blocks for Form Reform. The Table Picker Input is preconfigured to connect to Universal Content Puller table display widgets. Advanced settings allow the Table Picker Input to be configured to pick data from other HTML tables.

Form Reform Developer

A growing suite of resources to assist those developing blocks, handlers and more complex forms for Form Reform.

Learn with a simple form

While you may have plans to implement some much more complex forms using Form Reform, we strongly recommend you start with a simple form such as our contact form example in order to review the basic principles of using Form Reform before you move onto anything bigger.

  1. Start by submitting the form at Getting Started - Your First Form a few times, even making some deliberate mistakes.
  2. Watch our Getting Started with Form Reform video to see how the form is built.
  3. Read through the rest of Getting Started - Your First Form for more details of how this form is built.
  4. Create a test page on your site to build your own version of Getting Started - Your First Form and experiment.
  5. Develop your test page with some of the concepts introduced by our further examples and experiment with some of the other form inputs.