Code Monkey home page Code Monkey logo

formplug's Introduction

Formplug

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.

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

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.

readme-screenshot

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.

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.

formplug's People

Contributors

aaronhipple avatar danielireson avatar dependabot[bot] avatar jmbcpi avatar karanrajpal14 avatar simoneismann avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

formplug's Issues

Not processing emails that aren't whitelisted

I'd like to reference #19 but have this as a separate issue in-case someone has the same problem. I did follow your suggestion and added the header but I still seem to be facing issues.

Firstly, here's the curl call that I am using:

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode '[email protected]' \
--data-urlencode 'message=test' \
--data-urlencode 'name=test' \
--data-urlencode 'email=test'

This throws an error stating that I have not whitelisted this particular email. Well, the documentation states that "Whitelisted Recipients" are not required. Which is why I've chosen to leave them blank. Here's what my config.json looks like:

{
  "SERVICE_NAME": "karanr-form-backend",
  "ENCRYPTION_KEY": "<key>",
  "REGION": "us-west-2",
  "STAGE": "dev",
  "SENDER_ARN": "<arn>",
  "WHITELISTED_RECIPIENTS": []
}

But, when I do make the call, I get an error saying:

{
    "statusCode": 422,
    "message": "Non-whitelisted email in '_to' field"
}

Also, I did try adding in my email to the whitelist like so:

{
  "SERVICE_NAME": "karanr-form-backend",
  "ENCRYPTION_KEY": "<key>",
  "REGION": "us-west-2",
  "STAGE": "dev",
  "SENDER_ARN": "<arn>",
  "WHITELISTED_RECIPIENTS": ["[email protected]"]
}

But, to no avail. I then get an error like so:

{
    "statusCode": 500,
    "message": "An unexpected error occurred"
}

Do you have any idea what's going wrong? Any suggestions?

Missing required request parameters: [format]

Sorry for beginner question, but no experience with serverless concepts till now... :(

Tried to follow all instructions in this repos README and on the serverless site. config.json is all set and deploy worked. But when I send a test form to the url I get "Missing required request parameters: [format]"

Any idea or help with that, please?

IP addresses and `localhost` are rejected as invalid in `_redirect`

Formplug seems to be rejecting redirects to IP addresses or to localhost as invalid.

In my case, I'm using Zola, which in local development serves by default at http://127.0.0.1:1111. I've tried _redirect value(s) like "http://127.0.0.1:1111/thank-you" and "http://localhost:1111/thank-you" and they've been fairly consistently rejected. This appears to be down to this regex:

https://github.com/danielireson/formplug-serverless/blob/ad493385bea1d07b14b29da9f30ab2bbe6a1e920/src/lib/validation.js#L1-L3

It's not strictly necessary to get this working to verify the behavior I want in our production use-case, but it's an annoyance, and there may be other use cases where redirecting to an IP address or to localhost are desirable.

feature request: HTML-Mail

Will it be possible to send HTLM-Mails with formplug in near future or are there restrictions at AWS?

Multiple Email Addresses

Hi. Thanks for this great plugin, as well as the recent write-up explaining how it works!

I've been working on taking down some old drupal sites into HTML as they are no longer supported, and many may be easily hosted on S3. The problem with this is the contact form functionality, which formplug resolves very easily, compared to other more involved lambda setups.

However, some of our contact forms send to multiple email addresses. Is there a way to post a string of email addresses, or any plans to implement this feature?

Either way, much gratitude.

Missing authentication token

Hi,

I've been setting up formplug for the second time. The first time was for my own website running on my own server and is working flawlessly.

Now i'm trying to add it to a friends website but i'm receving 403 error on form submit:

The error header seen is: x-amzn-errortype: MissingAuthenticationTokenException

And also when I try to call the API directly I get the same 403 error:
{
"message": "Missing Authentication Token"
}

I've got no clue where stuff is going wrong or what auth token I should add where to make it work. Any pointers and help is much appreciated.

How to limit form submission

Hello,

First, thank you for your project, it works great!

I was wondering, apart from the honeypot, did you think of any way to limit form submission (based on IP for example)?

Thanks again.

Beginner Question

I think I'm a little confused. I've installed Serverless and setup my AWS credentials with it. Now I'm at npm install dependencies. Am I supposed to clone/copy the whole formplug-serverless repository into my project?

Invalid _to recepient

Hello,

I'm having trouble getting this work. I've deployed the backend and I'm trying to test it via Postman. Here's what the curl call looks like:

curl --location --request POST 'https://hgwaf31jxa.execute-api.us-west-2.amazonaws.com/dev/?format=json' \
--header 'Content-Type: multipart/form-data; boundary=--------------------------505726920421207878101501' \
--form '[email protected]' \
--form 'message=test \
--form 'name=test' \
--form 'email=test'

The response is:

{
    "statusCode": 422,
    "message": "Invalid '_to' recipient"
}

I've completed my SES verification and also tried adding my email to the whitelisted domains array but to no avail. I've also tried using the encrypted email but that doesn't work either. Mind helping me out?

Internal Server Error

I followed this guide and keep getting Internal Server Error how do I resolve this ?

I am using this example

            <form action="https://my api gateway url/to/my verified email address" method="post">
                <input type="text" name="name">
                <input type="submit" value="Send">

Even the form on your site is not working

reCaptcha to hCaptcha

Hello everyone ๐Ÿ˜„

Does anyone has tried to change from reCaptcha to hCaptcha?

I've tried to do it but I'm missing something.

https://docs.hcaptcha.com/switch#serverside

I updated the site verify URL from https://www.google.com/recaptcha/api/siteverify to https://hcaptcha.com/siteverify. However, I couldn't find anything else to change.

Can anyone give some tips here?

Thank you!! ๐Ÿš€

Checkboxes ignored

I use Twitter Bootstrap with which I created some checkboxes. The checkboxes get ignored while sending the e-mail via Formplug.

I'm not very good at front-end, so what did I miss here?

Thanks.

          <label for="autorijdenhinder" class="col-sm-3 col-form-label">Hebt u hinder tijdens het autorijden (meerdere antwoorden mogelijk)?</label>
          <div class="col-sm-6">
            <div class="form-check">
              <label class="form-check-label">
                <input class="form-check-input" type="checkbox" value="Test1">
                Concentratieproblemen en doezelen bij korte ritjes van max 30 min
              </label>
            </div>
            <div class="form-check">
              <label class="form-check-label">
                <input class="form-check-input" type="checkbox" value="Test2">
                Concentratieproblemen en doezelen bij langere autoritten van min 30 min
              </label>
            </div>
            <div class="form-check">
              <label class="form-check-label">
                <input class="form-check-input" type="checkbox" value="Test3">
                Concentratieproblemen en doezelen als bijrijder
              </label>
            </div>
            <div class="form-check">
              <label class="form-check-label">
                <input class="form-check-input" type="checkbox" value="Test4">
                Slaapmomenten tijdens autorijden
              </label>
            </div>
          </div>
        </div>```

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.