Formulate

A backend server application that listens for web form submissions, implemented with the rocket framework (0.5 release candidate). Minimum supported rust version (MSRV) is 1.65.0.

formulate is currently capable of using the host server's (or container's) built-in sendmail functionality to send email, after successfully receiving form data.

Configuration

Configuration is currenly very simple. Configuration keys are added to the [application] table with the desired values. Two email address keys, sending_email and destination_email, are required. These email addresses may be set in the Rocket.toml configuration file (e.g. Rocket.template.toml).

Alternatively, two environment variables: FORMULATE_destination_email and FORMULATE_sending_email may be used to provide the values. Configuration overriding follows that of the Rocket framework, so if both the config file and environment variables are set, the environment variables take precedence.

destination_email should be the email address you would like the form submissions sent to.

sending_email is the address the emails will come from once delivered to your inbox. It is meant to be a stable address which you can use to filter your form submission emails. This "sending email" will be used in the email's 'From:' header.

Any replies will be set to the 'Reply-To' address, which will be the email address set by the form's user.

Relaying email

Another pair of configuration variables, mail_relay_host and mail_relay_port, are optional. These are used if relaying emails via the SMTP protocol is desired.

mail_relay_host defines the hostname for the relaying mail server.

• May also be set using the FORMULATE_mail_relay_host environment variable.

mail_relay_port defaults to port 25 if not set, and allows users to choose an alternate port which the mail relay is listening on.

• May also be set using the FORMULATE_mail_relay_port environment variable.

SPAM blocklist

Rudimentary SPAM blocking functionality is now available. Optional blocklist functionality can be enabled with the addition of a blocklist key to a [spam] table.

If present, blocklist should be an array of strings formatted as domain names. These strings will be searched for in the form's message body and—if any match is found—result in form processing ending early. An error will also be provided, with a message indicating the form submission is suspected SPAM.

An example list is provided in Rocket.template.toml, and is free to be used by anyone.

• This feature can also be enabled using the FORMULATE_SPAM_blocklist environment variable. e.g. FORMULATE_SPAM_blocklist=['acme.com', 'mega.lo.mania']

Stop Forum SPAM API

Additional SPAM mitigation techniques have been added by checking the email addresses submitted by form users against the stopforumspam.org API. Enabling this feature will make formulate slower because it has to make a network request to the API. It is also possible that network issues, or problems with the API itself result in failures. Any failure communicating with the API, or obtaining results from the API will result in the check being skipped. We only take into account positive hits in considering the email addresses valid SPAM.

Enabling this feature is done by setting the blocking=true in the [spam] table. The environment variable FORMULATE_SPAM_blocking may also be used to enable this feature.

Accepted Form Fields

It accepts the following parameters, most of which are required:

• email: The email address of the form sender. This will be set as the 'Reply-To' address in the sent email. Can also be submitted as e-mail.
• full_name: The name the form sender would like to use in the sent email. This will be used as the email sender name. Can also be submitted as fullname.
• from_site: The URL of the site from which the form is submitted. May also be submitted as site, website, or location. Alternatively, for url-encoded form submissions, this can be set to the URL of the page the user should be redirected to if the form was submitted successfully. This form field may be hidden and set via JavaScript before submission.
• message: The message body of the sent email.
• subject: (optional) The title of the email. A default subject will be used if this is not provided.
• redirect: (optional) Boolean value used to indicate if user wants non-JSON submissions to be redirected to from_site URL.

After passing the email on to sendmail, formulate responds with appropriate HTTP status codes to indicate success or failure.

Successful URL-encoded or Multi-part submissions will be redirected to the URL defined in the from_site field when the redirect field is set to true. If redirect is omitted, or false, a message with an appropriate HTTP status is provided. On failure, a user readable error is provided, along with the appropriate HTTP status.

JSON form submissions receive a JSON response with appropriate success or failure messages and HTTP statuses.

Deployment

A Dockerfile is included in the git repository and may be used as a starting point for containerized deployments on Linux.

An rc script is also provided to aid in deployment on FreeBSD platforms.

Dependencies

A description of the project dependencies and some reasoning behind why they were added can be found in README.dependencies.