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="johndoe@example.com">
    <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="johndoe@example.com">Recipient option 1</option>
  <option value="janedoe@exmaple.com">Recipient option 2</option>
</select>

Separate multiple email addresses by a semicolon.

<!-- plain text emails -->
<input type="hidden" name="_cc" value="johndoe@example.com;janedoe@exmaple.com">

<!-- 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", "johndoe@example.com");
fetchParams.append("message", "");

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

Special inputs

Name	Description	Multiple emails	Required
_to	Email address of the primary recipient.	N	Y
_cc	Email addresses to receive a carbon copy.	Y	N
_bcc	Email addresses to receive a blind carbon copy.	Y	N
_replyTo	Email addresses to set as reply to addresses.	Y	N
_honeypot	A spam prevention field that should be hidden for regular website users. The submission will be ignored if the the _honeypot input is present and not empty.	/	N
_recaptcha	User token from Google reCaptcha v3.	/	N
_redirect	A URL to redirect users to after a successful form submission.	/	N

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 johndoe@example.com
ff17d6a0cd474813adc031a9b24855090b5e8b

> npm run decrypt ff17d6a0cd474813adc031a9b24855090b5e8b
johndoe@example.com

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.

Name	Description	Required
SERVICE_NAME	The private name for the service.	Y
ENCRYPTION_KEY	A random string used for encryption.	Y
REGION	The AWS region to deploy to (this should be either eu-west-1, us-east-1, or us-west-2 as these are the only SES supported regions).	Y
STAGE	The AWS stage to deploy to (it's common to use dev or prod).	Y
SENDER_ARN	The ARN of the sender email address.	Y
MSG_RECEIVE_SUCCESS	This is returned to the user on a successful form submission if a redirect URL isn't provided.	N
MSG_SUBJECT	The subject line to use in emails.	N
WHITELISTED_RECIPIENTS	Only allow emails to be sent to specific addresses.	N
RECAPTCHA_SECRET_KEY	Site secret key for reCaptcha v3.	N

Deploy

Run serverless deploy to deploy to AWS.