# Formulate Rust backend service that listens for web form submissions. It is built using the [Rocket](https://rocket.rs) framework and has a minimum supported rust version (MSRV) of 1.67.1. ## Configuration Configuration is done using either a toml file or environment variables. 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](https://code.orbitsolutions.dev/orb-it-solutions/formulate/src/branch/master/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. If both the config file and environment variables are set, the config file will 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. The *'Reply-To'* address will be the email address submitted 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. If the mail relay being used requires authentication the optional `smtp_username` and `smtp_password` config variables allow setting those. `smtp_username` defines the login (email address) used to authenticate with the `mail_relay_host` SMTP server. - May also be set using the `FORMULATE_smtp_username` environment variable. `smtp_password` sets the password used to authenticate with the `mail_relay_host` SMTP server. - May also be set using the `FORMULATE_smtp_password` environment variable. This allows users the flexibility of using `formulate` to send emails via locally available `sendmail` (or sendmail alternative), an email service or a personal email account. ### SPAM allowlist/blocklist Rudimentary SPAM blocking functionality is also available in `formulate`. This optional functionality can be enabled with the addition of the `blocklist` or `allowlist` keys to the `[spam]` table. If present, `blocklist` or `allowlist` should be an [array](https://toml.io/en/v1.0.0#array) of strings formatted as domain names. #### Blocklist When configured, strings in the `blocklist` 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 of being SPAM. An example list is provided in [Rocket.template.toml](https://code.orbitsolutions.dev/orb-it-solutions/formulate/src/branch/master/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"]` #### Allowlist Configuring `allowlist` results in the configured strings being used to match against URLs found in the form's message body. If *any* of the urls *do not match* any of the allowed domains, form processing is ended early. An error will also be provided, with a message indicating the form submission is suspected of being SPAM. A sample config is shown in [Rocket.template.toml](https://code.orbitsolutions.dev/orb-it-solutions/formulate/src/branch/master/Rocket.template.toml). - This feature can also be enabled using the `FORMULATE_SPAM_allowlist` environment variable. e.g. `FORMULATE_SPAM_allowlist=["good.domain.com", "gooder.domain.com"]` ### 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. `formulate` only takes into account positive hits when determining if email addresses are 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: - *`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. Is also aliased to *`fullname`*, *`full-name`*, *`firstname`*, *`first-name`* and *`first_name`*. - *`last_name`*: (**optional**) If getting the full name in two separate fields is desired, the "family" name can be optionally submitted as this. Is also aliased as *`lastname`* and *`last-name`*. - *`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. - *`company_name`*: (**optional**) Intended for accepting company name form submissions. Is aliased to *`companyname`* and *`company-name`*. - *`phone_number`*: (**optional**) Intended for accepting phone number form submissions. Is aliased to *`phonenumber`* and *`phone-number`*. - *`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](https://code.orbitsolutions.dev/orb-it-solutions/formulate/src/branch/master/README.dependencies.md).