Email Form Handler

This script takes the user's form inputs and sends the details in a templated HTML email to the site admin, and optionally a confirmation email to the user.

Data from your form is submitted to this script, which is then processed and sent via the Swiftmailer email library.

We've taken the hard work out of setting up contact forms. By configuring settings in the forms/smtp.php file you can easily send rich emails to the site owner and user alike.

Forms can be protected by Google reCAPTCHA v2 (Checkbox and Invisible reCAPTCHA). See our reCAPTCHA docs for more detail.

The script returns JSON data to interface with the form javascript on the browser side.

Features

• Swiftmailer Library
• SMTP with optional TLS/SSL
• reCAPTCHA
• Plain Text + HTML included in emails
• Save submissions to CSV file
• HTML templated email to site owner
• HTML templated confirmation message to user
• JSON response to interface with form scripts provided with theme.

To use the smtp.php form handler you will need the following;

• An email account from which to send the email
• SMTP server details for the email account
• A PHP server > 5.4
• Configuration of settings in forms/smtp.php

When your user submits a form:

• The input is passed to smtp.php.
• User's input is processed.
• Inputs are inserted into an HTML template.
• An email is constructed from the template.
• Your web server uses Swiftmailer library to connect to an SMTP server and send an email to the specified address.
• Optionally a templated HTML email can be sent to the user as confirmation.
• Optionally the submission data can be saved to a CSV file.
• Success/error feedback is passed back to the browser as JSON.

Set up a new email account on a reliable SMTP server to handle sending emails.

We recommend using an SMTP server associated with your hosting account if possible. This is to minimise any potential communication issues between the web server and the SMTP server.

Some SMTP servers are difficult to work with. We don't recommend using Gmail as your sending server for the following reasons:

• Gmail servers are particular about security, and you will need to make adjustments in your account's security settings in order to send the email from a Gmail account.
• If you use two-factor authentication with your Google account, a Single App Password will need to be used.
• Gmail will refuse to connect to some host's web servers - such as GoDaddy. This may be because the shared hosting server's IP address is blacklisted by Gmail for historical spamming offences.

All email settings are contained in forms/smtp.php.

Configuration takes the form of PHP variable declaration. All of the variables are already set up with dummy data.

Change the values on the right hand side of the = sign leaving the quotes intact. Values such as true, false and null should not have quotes.

All settings are required.

Server Connection Settings

Variable	Description
$outgoingServerAddress	Hostname or IP address of the sending server to use.
$outgoingServerPort	Port number used to connect to SMTP server. Usually "25" or "587".
$outgoingServerSecurity	Security protocol configured on your SMTP server. Supported types are "ssl", "tls" or null.

Sending Account Settings

Variable	Description
$sendingAccountUsername	Username for the email account that will send the email. Often this is the email address itself.
$sendingAccountPassword	Password for the sending account.

Admin Recipient Settings

Variable	Description
$recipientEmail	Email address of the intended recipient - usually the site owner or admin.
$recipientName	The name for the To: field of the email.

Email to Admin Settings

Variable	Description
$emailSubject	Subject of the email that the admin will see.
$websiteName	Used as the From: name on the email.
$adminEmailTemplate	Filename of the template to be used for the admin email. Must be a file in the templates folder see Admin Email Template section below.

Feedback Settings

Variable	Description
$successMessage	Message to be shown to user when form submission was successfully received and email was successfully sent.

reCAPTCHA Settings

Variable	Description
$recaptchaSecretKey	Optional. If your form contains a reCAPTCHA widget, or uses invisible reCAPTCHA, place your secret key here. See reCAPTCHA documentation for more detail.
$recaptchaErrorMessage	Optional. If using reCAPTCHA, this is an explanation to the user for when a reCAPTCHA error occurs.

Confirmation Email Settings

Variable	Description
$sendConfirmationToUser	Enable or disable confirmation email to the user. Accepts true or false.
$userEmailField	Name of the form field which captured the user's email address. Usually "email" or "contact-email"
$userNameField	Name of the form field which captured the user's name.
$confirmationEmailTemplate	Filename of the template to be used for the confirmation email. Must be a file in the templates folder see Admin Email Template section below.
$confirmationSubject	Subject of the confirmation email.
$confirmationFromName	Used in the From: field of the confirmation email.
$confirmationReplyTo	Input an email address. If the user hits Reply on the confirmation email, this is the address where the reply will be sent.
$confirmationReplacements	Please see Confirmation Email Template section below.

CSV Settings

Variable	Description
$saveToCSV	Enable or disable saving user input to CSV file. Accepts true or false.
$saveToCSVFileName	A relative path to a file where the CSV data should be stored eg. "csv/csv_forms_email_1.csv" saves in forms/csv folder. If the file does not exist, it will be created.

Located in the forms/templates/email_to_admin.html file is a basic HTML template used as the default content for the email sent out to the site owner.

Templates must be located in the templates folder, and you may edit the template however you see fit.

The admin template has access to the $_POST variable only. This is the form data sent from the user to the server.

Output form data to the email template using tags with double square brackets, which are replaced with the text from the corresponding form input:

User's email address: [[contact-email]]

outputs:

User's email address: user@domain.com

Square brackets must not contain spaces, and must match the name of a form input on the page.

Any other text in the template is output as normal. The template should contain valid HTML compatible with an email reader app.

The text version of the email will contain a basic readout of the user's inputs listed by name of the input field.

Located in the forms/templates/confirmation_to_user.html file is a basic HTML template. This is used as the default content for the confirmation email sent to the user.

Templates must be located in the templates folder, and you may edit the template however you see fit.

Data for the confirmation template is specified in the $confirmationReplacements array in smtp.php. In the resulting email, the text provided in each key of the array (left of the => arrow) will be replaced by its value (right side of the => arrow).

Include dynamic data in the email by inserting the tags from the $confirmationReplacements keys where necessary in the template.

This example shows how the text [[contact-email]] and [[webAddress]] will be replaced by values in the array.

// array specified in smtp.php
$confirmationReplacements  = array( 
    "[[contact-email]]"  => $_POST["contact-email"],
    "[[webAddress]]"     => 'http://mrare.co',
);


// Template text in forms/templates/confirmation-to-user.html
Thanks for your enquiry, we'll contact you on the following email address: [[contact-email]]
Feel free to contact us any time through our website at [[webAddress]]


// Transformed output sent to the user
Thanks for your enquiry, we'll contact you on the following email address: user@domain.com
Feel free to contact us any time through our website at http://mrare.co

Any other text in the template is output as normal. The template should contain valid HTML compatible with an email reader app.

The text version of the confirmation email will contain a basic copy of the HTML version with all HTML <tags> stripped.

In some instances you may have a need for two forms on the same site to submit to two separate addresses using different templates.

This is simply a matter of creating two different versions of smtp.php to handle the different cases.

• Copy the original smtp.php file and rename it eg. smtp-contact-2.php
• Point the new form's action attribute to the new file: action="forms/smtp-contact-2.php"
• Edit the details of smtp-contact-2.php to meet your needs for the second form.

Common errors that may arise during configuration of form handlers:

Common Errors

Error	Description
Connection refused	Could be caused by the SMTP server rejecting the connection from your web server or your web server may be behind a firewall and cannot reach the outside network. Contact your hosting provider to ascertain if this is the case.
Internal Server Error	This is a very general error and can be hard to diagnose. Generally this is a syntax error in your smtp.php file. You can copy your code to an online PHP code checker to help identify problems in the syntax, or uncomment the first two lines of smtp.php to reveal more descriptive PHP error messages. Alternatively, check the error logs on your server for detailed information.
200 JSON Parse error, unexpected '<'	The server is not returning JSON, instead it is producing error text in HTML format, so jQuery can't handle it as JSON. Check the network tab in your browser developer tools, locate the smtp.php request and view the response to read the full error text.
There was an error verifying the Google reCaptcha	Check that your secret key is properly set in smtp.php.