Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status

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.



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="" method="post">
    <input type="hidden" name="_to" value="">
    <input type="text" name="message">
    <input type="submit" value="send">

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

<select name="_to">
  <option value="">Recipient option 1</option>
  <option value="">Recipient option 2</option>

Separate multiple email addresses by a semicolon.

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

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

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


Append format=json to the query string to get responses back in JSON with a CORS allow all origin header.

<form action="" method="post">
    <input type="hidden" name="_to" value="">
    <input type="text" name="message">
    <input type="submit" value="send">

Spam prevention


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.


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">


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=""></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


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

Submission preview


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 => ff17d6a0cd474813adc031a9b24855090b5e8b
> npm run decrypt ff17d6a0cd474813adc031a9b24855090b5e8b
ff17d6a0cd474813adc031a9b24855090b5e8b =>


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


Run serverless deploy to deploy to AWS.