email

Last updated Mar 26th, 2021 | Page history | Improve this page | Report an issue

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

Budget

$301 per month—let's make that $500!

Learn more

FormIt email Hook¶

The email hook will email out your form contents to any email(s).

Available Properties¶

name	description
emailTpl	Required. Tpl chunk for email message. If one is not specified, it will send a list of fields with their values.
emailSubject	The subject of the email.
emailUseFieldForSubject	If 1, and the field 'subject' is passed, then will use that field's value as the email's subject line.
emailTo	A comma-separated list of emails to send to.
emailToName	Optional. A comma-separated list of names to pair with the emailTo values.
emailFrom	Optional. If set, will specify the From: address for the email. If not set, will first look for an `email` form field. If none is found, will default to the `emailsender` system setting. NOTE: Always set the emailFrom to a valid emailaddress (that is allowed to send from your server) to avoid rejected emails due to SPF/ DMARC violations.
emailFromName	Optional. If set, will specify the From: name for the email.
emailHtml	Optional. Whether or not the email should be in HTML-format. Defaults to 1.
emailConvertNewlines	Optional. If set to 1, will convert all newlines to br tags.
emailReplyTo	An email to set as the reply-to. If not set, will first look for an `email` form field. If none is found, will default to value set in `emailFrom`. NOTE: Set emailReplyTo to valid emailaddress from the same domain as `emailFrom` to avoid rejected email due to SPF/DMARC violations.
emailReplyToName	Optional. The name for the Reply-To field.
emailCC	A comma-separated list of emails to send via cc.
emailCCName	Optional. A comma-separated list of names to pair with the emailCC values.
emailBCC	A comma-separated list of emails to send via bcc.
emailBCCName	Optional. A comma-separated list of names to pair with the emailBCC values.
emailMultiWrapper	Wraps values submitted by checkboxes/multi-selects with this value. Defaults to just the value. (1.6.0+)
emailMultiSeparator	Separates checkboxes/multi-selects with this value. Defaults to a newline. (1.6.0+)
emailSelectField	The name of the form field, that selects the email addresses to send to. (4.2.5+)
emailSelectTo	A semicolon separated list of comma separated email addresses to send to. (4.2.5+)
emailSelectToName	A semicolon separated list of comma separated email names to send to. (4.2.5+)

Any of the email hook properties can have placeholders of field names from your form in them that will be evaluated.

Usage¶

Simply specify it as a hook in your FormIt call, and then specify the email-specific properties in the FormIt call as well.

[[!FormIt?
    ...
    &hooks=`email`
    &emailTpl=`CentralizedDebtObligationEmailTpl`
    &emailSubject=`Some Sucker Bought Another CDO`
    &emailTo=`[email protected]`
    &emailCC=`[email protected]`
    &emailBCC=`[email protected]`
    &emailBCCName=`CDO Fraud Informant`
]]

Note the &emailTpl property points to the name of a Chunk. In that Chunk, you'll have placeholders for each field in your form. Our Chunk could look like this:

<p>Hello,</p>
<p>[[+name]] just purchased the CDO package: [[+cdo_package]].</p>
<p>Their email: [[+email]]</p>
<p>Thanks!</p>

This assumes, of course, that you have the fields "name", "cdo_package" and "email" in your form.

Specifying Dynamic To Addresses¶

FormIt, as of 4.2.5+, could select the receiver of the mail by the numeric value of a field i.e. by the option value of a select. By doing this, you could avoid to create a spoofable form field, where a frontend user could submit any mail address quite easily. The frontend user would only see a numbered list of receivers that are translated to email addresses by FormIt properties.

For this, you could use the following FormIt properties

&emailSelectTo=`[email protected],[email protected];[email protected]`
&emailSelectToName=`Mail1,Mail2;Different`
&emailSelectField=`emailselect`

and the following form field

<select name="emailselect">
    <option value="1" [[!+fi.emailselect:default=`1`:FormItIsSelected=`1`]]>Address 1</option>
    <option value="2" [[!+fi.emailselect:default=`1`:FormItIsSelected=`2`]]>Address 2</option>
</select>

If Address 1 is selected, the mail would be sent to [email protected],[email protected], if Address 2 is selected, the mail would be sent to [email protected].

Using a Subject Field as the Email Subject Line¶

Let's say you have a subject field in your form. You want that to be the subject of the email sent out. The email hook has the ability to do this:

[[!FormIt?
    ...
    &emailUseFieldForSubject=`1`
]]

This will then look for a field named "subject" that will be used in the email. If it's not found or empty, it will default to the &emailSubject property.

Handling Checkboxes and Multi-Selects in the Email¶

FormIt, as of 1.6.0+, will automatically handle checkboxes and combine them into one field. You can use the &emailMultiSeparator and &emailMultiWrapper properties to specify how they are joined. For example, to wrap checkboxes in LI tags:

[[!FormIt?
    ...
    &emailMultiWrapper=`<li>[[+value]]</li>`
]]

Or just to separate them with BR tags:

[[!FormIt?
    ...
    &emailMultiSeparator=`<br />`
]]