Building a serverless contact form with AWS Lambda and AWS SES

What if I told you it can be done with zero dependencies? Hope you’re up for a challenge because that’s exactly what we’ll be doing.

This tutorial will cover the basics of both the front-end contact form, with vanilla JavaScript, and the serverless back end hosted on AWS LambdaAWS SES is the service you use for sending the actual emails and trust me, it’s so incredibly simple the configuration takes 13 seconds. Yes, I timed myself.

Well, okay then. Let’s jump in!


Just to make sure you have an overview of what we’re doing today, here’s a short TL;DR. You can jump to the section that interests you, and severely hurt my feelings, or just keep reading from here. Take your pick… I won’t silently judge you. ?

Note: I turned this code into an npm module for easier re-usability, and so you peeps don’t need to write all the code yourself when you need a quick contact form.

What are we building?

The general idea is to build a contact form that can be added to a static website. We want to add it without managing any servers and ideally not paying anything for it to run. Here’s an amazing use case for AWS Lambda.

The structure of what we want to build is rather simple. We have a simple form, with a tiny snippet of JavaScript to parse the parameters to JSON and send them to an API endpoint.

The endpoint is an AWS API Gateway event, which will trigger an AWS Lambda function. The function will tell AWS SES to send an email with the content to your email address. From there you can continue exchanging emails with the person who filled out the form. Simple, right?

aws services

Let’s start hacking!

Configure AWS SES

In order to send emails with the Simple Email Service AWS provides, you need to verify an email address which will be used to send the emails. It’s as simple as navigating to the AWS Console and searching for Simple Email Service.

SES configuration

Once there press the Email Addresses link on the left side navigation. You’ll see a big blue button called Verify a New Email Address. Press it and add your email address.


AWS will now send you a verification email to that address. Go ahead and verify it. That’s pretty much it. Ready to write some code now?

Build the API with the Serverless Framework

There are a couple of main steps in building the actual API. The first thing, as always, is the configuration.

1. Install the Serverless Framework

In order for serverless development to not be absolute torture, go ahead and install the Serverless framework.

$ npm i -g serverless

Note: If you’re using Linux, you may need to run the command as sudo.

Once installed globally on your machine, the commands will be available to you from wherever in the terminal. But for it to communicate with your AWS account you need to configure an IAM User. Jump over here for the explanation, then come back and run the command below, with the provided keys.

$ serverless config credentials \
    --provider aws \
    --key xxxxxxxxxxxxxx \
    --secret xxxxxxxxxxxxxx

Now your Serverless installation knows what account to connect to when you run any terminal command. Let’s jump in and see it in action.

2. Create a service

Create a new directory to house your Serverless application services. Fire up a terminal in there. Now you’re ready to create a new service.

What’s a service you ask? View it like a project. But not really. It’s where you define AWS Lambda functions, the events that trigger them and any AWS infrastructure resources they require, all in a file called serverless.yml.

Back in your terminal type:

$ serverless create --template aws-nodejs --path contact-form-api

The create command will create a new service. Shocker! But here’s the fun part. We need to pick a runtime for the function. This is called the template. Passing in aws-nodejs will set the runtime to Node.js. Just what we want. The path will create a folder for the service.

3. Explore the service directory with a code editor

Open up the contact-form-api folder with your favorite code editor. There should be three files in there, but for now, we’ll only focus on the serverless.yml. It contains all the configuration settings for this service. Here you specify both general configuration settings and per function settings. Your serverless.yml will be full of boilerplate code and comments. Feel free to delete it all and paste this in.

# serverless.yml

service: contact-form-api

  secrets: ${file(secrets.json)}

  name: aws
  runtime: nodejs8.10
  stage: ${self:custom.secrets.NODE_ENV}
  region: us-east-1
    NODE_ENV: ${self:custom.secrets.NODE_ENV}
    EMAIL: ${self:custom.secrets.EMAIL}
    DOMAIN: ${self:custom.secrets.DOMAIN}
    - Effect: "Allow"
        - "ses:SendEmail"
      Resource: "*"

    handler: handler.send
      - http:
          path: email/send
          method: post
          cors: true

The functions property lists all the functions in the service. We will only need one function though, to handle the sending of emails. The handler references which function it is.

Take a look at the iamRoleStatements, they specify the Lambda has permission to trigger the Simple Email Service.

We also have a custom section at the top. This acts as a way to safely load environment variables into our service. They’re later referenced by using ${self:custom.secrets.<environment_var>} where the actual values are kept in a simple file called secrets.json.


4. Add the secrets file

We all know pushing private keys to GitHub kills little puppies. Please don’t do that. Handling this with the Serverless Framework is simple. Add a secrets.json file and paste these values in.


While testing you can keep the domain as '*', however, make sure to change this to your actual domain in production. The EMAIL field should contain the email you verified with AWS SES.

5. Write business logic

With that wrapped up, let’s write the actual code. All in all, the code itself is rather simple. We’re requiring the SES module, creating the email parameters, and sending them with the .sendMail() method. At the bottom, we’re exporting the function, making sure to make it available in the serverless.yml.

const aws = require('aws-sdk')
const ses = new aws.SES()
const myEmail = process.env.EMAIL
const myDomain = process.env.DOMAIN

function generateResponse (code, payload) {
  return {
    statusCode: code,
    headers: {
      'Access-Control-Allow-Origin': myDomain,
      'Access-Control-Allow-Headers': 'x-requested-with',
      'Access-Control-Allow-Credentials': true
    body: JSON.stringify(payload)

function generateError (code, err) {
  return {
    statusCode: code,
    headers: {
      'Access-Control-Allow-Origin': myDomain,
      'Access-Control-Allow-Headers': 'x-requested-with',
      'Access-Control-Allow-Credentials': true
    body: JSON.stringify(err.message)

function generateEmailParams (body) {
  const { email, name, content } = JSON.parse(body)
  console.log(email, name, content)
  if (!(email && name && content)) {
    throw new Error('Missing parameters! Make sure to add parameters \'email\', \'name\', \'content\'.')

  return {
    Source: myEmail,
    Destination: { ToAddresses: [myEmail] },
    ReplyToAddresses: [email],
    Message: {
      Body: {
        Text: {
          Charset: 'UTF-8',
          Data: `Message sent from email ${email} by ${name} \nContent: ${content}`
      Subject: {
        Charset: 'UTF-8',
        Data: `You received a message from ${myDomain}!`

module.exports.send = async (event) => {
  try {
    const emailParams = generateEmailParams(event.body)
    const data = await ses.sendEmail(emailParams).promise()
    return generateResponse(200, data)
  } catch (err) {
    return generateError(500, err)

That’s it, all about 60 lines of code, with absolutely no dependencies. Sweet!

Deploy the API to AWS Lambda

Here comes the easy part. Deploying the API is as simple as running one command.

$ serverless deploy serverless deploy

You can see the endpoint get logged to the console. That’s where you will be sending your requests.

Test the API with Dashbird

The simplest way of testing an API is with CURL. Let’s create a simple CURL command and send a JSON payload to our endpoint.

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"email":"","name":"John Doe","content":"Hey!"}' \

If everything works like it should, you will get an email shortly. If not, well then you’re out of luck. In cases like these, I default to using Dashbird to debug what’s going on.


The logs on my end are showing all green, so it’s working perfectly! That’s the API part done. Let’s move on to the contact form itself.

Build the contact form

Because I’m not the best CSS guru in the world, I’ll just entirely skip that part and show you how to make it work. ?

Let’s start with the HTML markup.

<form id="contactForm">
  <input type="text" placeholder="Name" name="name" required>
  <label>Email Address</label>
  <input type="email" placeholder="Email Address" name="email" required>
  <textarea rows="5" placeholder="Message" name="content" required></textarea>
  <div id="toast"></div>
  <button type="submit" id="submit">Send</button>

It’s an incredibly simple form with three fields and a button. Let’s move on to the JavaScript.

const form = document.getElementById('contactForm')
const url = 'https://{id}.execute-api.{region}{stage}/email/send'
const toast = document.getElementById('toast')
const submit = document.getElementById('submit')

function post(url, body, callback) {
  var req = new XMLHttpRequest();"POST", url, true);
  req.setRequestHeader("Content-Type", "application/json");
  req.addEventListener("load", function () {
    if (req.status < 400) {
      callback(null, JSON.parse(req.responseText));
    } else {
      callback(new Error("Request failed: " + req.statusText));
function success () {
  toast.innerHTML = 'Thanks for sending me a message! I\'ll get in touch with you ASAP. :)'
  submit.disabled = false
  submit.blur() = '' = ''
  form.content.value = ''
function error (err) {
  toast.innerHTML = 'There was an error with sending your message, hold up until I fix it. Thanks for waiting.'
  submit.disabled = false

form.addEventListener('submit', function (e) {
  toast.innerHTML = 'Sending'
  submit.disabled = true

  const payload = {
    content: form.content.value
  post(url, payload, function (err, res) {
    if (err) { return error(err) }

Another 50 lines and you have the client side logic done. Feel free to drop this into your website, change the url constant to the API endpoint you deployed above. Hey presto, there’s your serverless contact form done and ready for production!

Wrapping up

There you have it, a quick and easy way to add a serverless contact form to a website. Using serverless for the odd, isolated endpoint like this is great. There are absolutely no servers you need to worry about. Just deploy the code and rest assured it’ll work. If something breaks, you have Dashbird watching your back, alerting you in Slack if something is wrong. Damn, I love Slack integrations.

Anyhow, I took the time to create an npm module out of the code above, so in the future, nobody needs to write this twice. Just install the package and there’s your contact form endpoint up and running in less than a minute. You can find the instructions in the GitHub repo, if you want to take a look. Give it a star if you want more people to see it on GitHub.

If you want to read some of my previous serverless musings head over to my profile or join my newsletter!

Or, take a look at a few of my articles right away:

Hope you guys and girls enjoyed reading this as much as I enjoyed writing it. If you liked it, feel free to share. Until next time, be curious and have fun.

We aim to improve Dashbird every day and user feedback is extremely important for that, so please let us know if you have any feedback about these improvements and new features! We would really appreciate it!

Read our blog

ANNOUNCEMENT: new pricing and the end of free tier

Today we are announcing a new, updated pricing model and the end of free tier for Dashbird.

4 Tips for AWS Lambda Performance Optimization

In this article, we’re covering 4 tips for AWS Lambda optimization for production. Covering error handling, memory provisioning, monitoring, performance, and more.

AWS Lambda Free Tier: Where Are The Limits?

In this article we’ll go through the ins and outs of AWS Lambda pricing model, how it works, what additional charges you might be looking at and what’s in the fine print.

More articles

Made by developers for developers

Dashbird was born out of our own need for an enhanced serverless debugging and monitoring tool, and we take pride in being developers.

What our customers say

Dashbird gives us a simple and easy to use tool to have peace of mind and know that all of our Serverless functions are running correctly. We are instantly aware now if there’s a problem. We love the fact that we have enough information in the Slack notification itself to take appropriate action immediately and know exactly where the issue occurred.

Thanks to Dashbird the time to discover the occurrence of an issue reduced from 2-4 hours to a matter of seconds or minutes. It also means that hundreds of dollars are saved every month.

Great onboarding: it takes just a couple of minutes to connect an AWS account to an organization in Dashbird. The UI is clean and gives a good overview of what is happening with the Lambdas and API Gateways in the account.

I mean, it is just extremely time-saving. It’s so efficient! I don’t think it’s an exaggeration or dramatic to say that Dashbird has been a lifesaver for us.

Dashbird provides an easier interface to monitor and debug problems with our Lambdas. Relevant logs are simple to find and view. Dashbird’s support has been good, and they take product suggestions with grace.

Great UI. Easy to navigate through CloudWatch logs. Simple setup.

Dashbird helped us refine the size of our Lambdas, resulting in significantly reduced costs. We have Dashbird alert us in seconds via email when any of our functions behaves abnormally. Their app immediately makes the cause and severity of errors obvious.