Formplug

Formplug is a form forwarding service for AWS Lambda. Use it to accept form submissions by email without server-side code. It's built using the Serverless Framework and uses Amazon SES to send emails.

Usage

HTML forms

Set the form action to your deployed Formplug endpoint. Email addresses can be passed in plain text (as in the example below) or encrypted as a hexedecimal string (see encryption).

<form action="https://apigatewayurl.com" method="post">
    <input type="hidden" name="_to" value="[email protected]">
    <input type="text" name="message">
    <input type="submit" value="send">
</form>

Use a select if you want to change the recipient based on a user choice without using JavaScript.

<select name="_to">
  <option value="[email protected]">Recipient option 1</option>
  <option value="[email protected]">Recipient option 2</option>
</select>

Separate multiple email addresses by a semicolon.

<!-- plain text emails -->
<input type="hidden" name="_cc" value="[email protected];[email protected]">

<!-- encrypted emails -->
<input type="hidden" name="_cc" value="ff19d0abcd474813ad;c031a9b24855090b5e8b">

AJAX

Append format=json to the query string to get responses back in JSON with a CORS allow all origin header. You can then make requests using a HTTP client.

const fetchParams = new URLSearchParams();
fetchParams.append("_to", "[email protected]");
fetchParams.append("message", "");

fetch("https://apigatewayurl.com?format=json", {
  method: "POST",
  body: fetchParams,
}).then(() => {
  // handle success
}).catch(() => {
  // handle failure
})

Special inputs

Spam prevention

Whitelisting

You can restrict where emails can be sent to by setting WHITELISTED_RECIPIENTS in config.json to an array of valid recipients. If this is not set then form submissions can be forwarded to any email address.

Honeypot

A honeypot field can be used as an easy to setup spam prevention measure. If the _honeypot input is not empty on a form submission then the request will be ignored. CSS should be used to hide the input from regular visitors.

<input type="text" name="_honeypot" value="" style="display:none">

reCaptcha

Google's reCaptcha v3 can be integrated for advanced spam prevention. This validates each form submission invisibly based on user interactions with your site. To setup, provide your site secret key in config.json as RECAPTCHA_SECRET_KEY and send the response token from execute as a _recaptcha field on each form submission.

<script src="https://www.google.com/recaptcha/api.js?render=RECAPTCHA_SECRET_KEY"></script>
<script>
grecaptcha.ready(function() {
    grecaptcha.execute('RECAPTCHA_SECRET_KEY').then(function(token) {
       // send token as _recaptcha with the rest of the form
       // this can be done by appending a hidden input to the form
       // or sending programatically using the Fetch API or similar
    });
});
</script>

Customisation

Create a HTML template at src/template/custom.html and this will be used instead of default.html for HTML form usage.

Encryption

Email addresses can be encrypted so that they're not visible in the HTML source. Ensure ENCRYPTION_KEY in config.json is set to a random value as this is used to determine the encrypted values.

> npm run encrypt [email protected]
ff17d6a0cd474813adc031a9b24855090b5e8b

> npm run decrypt ff17d6a0cd474813adc031a9b24855090b5e8b
[email protected]

Setup

Install Serverless

Follow the Serverless Framework AWS installation.

Setup SES identity

Amazon SES can only send emails from addresses that you have verified ownership of. Verification can be done using the AWS Management Console by visiting the SES Dashboard and heading to Identity Management. AWS also puts new SES accounts under limits which prevent emails from being sent to email addresses that haven't been verified. Check out the relevant AWS SES documentation for more information. The limits can be lifted by opening a support ticket.

Install dependencies

Run npm install to get the NPM dependencies.

Add config

Create a copy of config.sample.json as config.json and edit as appropriate.

Deploy

Run serverless deploy to deploy to AWS.