# Formulate
A backend server application that listens for web form submissions, implemented with the [rocket](https://crates.io/crates/rocket) framework (0.5 release candidate).
`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. Two email addresses, a `sending_email` and a `destination_email`, will need to be provided. These email addresses may be set in the `Rocket.toml` configuration file (see [Rocket.toml.template](https://code.orbitsolutions.dev/orb-it-solutions/formulate/src/branch/master/Rocket.toml.template) for an example).
Alternatively, two environment variables: `FORM_SUBMISSION_destination_email` and `FORM_SUBMISSION_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:'*.
Any replies will be set to the *'Reply-To'* address, which will be the email address set by the form's user.
## 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.