ValidateFast

Validate your idea in minutes, not days!

The AWS Serverless boilerplate with all you need to quickly deploy an email subscription enabled launch page for $1 per 10,000 emails sent.

Key Features

• Email Subscriptions and Broadcast: Broadcast plain-text email messages or HTML email messages effortlessly at AWS SES cost ($1 / 10,000 emails)

• Secure Email Database: Emails are collected in your DynamoDB tables and are fully accessible at all times. You own your data!

• S3 Site Hosting: Seamlessly edit and deploy your site. Simply edit the "site" HTML/CSS/JS folder and everything else is deployed for you.

• Do it again and again: Launch your first launch page and keep doing it again. Built with AWS CDK (Cloud Deployment Kit), launching a new launch page is as easy as copy and paste.

• Automatic GitHub repository invitation upon payment

Step-by-step setup

When deploying this template, the sequence of steps is important. Follow the steps below in order to get up and running.

Pre-requisite

• Domain - Ensure you have a domain name with accessible DNS settings for configuration. This can be obtained from any domain provider, but you must have control over its DNS, nameservers, and forwarding.

Quick Start with AWS CLI

To successfully deploy the project, we need a couple tools and assets.

1. AWS CLI is used by ValidateFast to configure resources in AWS cloud.
2. AWS CDK (Cloud Deployment Kit) is used by ValidateFast to deploy resources in AWS cloud.

Installing AWS CLI

1. Download and Install:

   • If you do not have AWS CLI installed, download it from the official AWS CLI page.
   • Follow the installation instructions provided for your operating system.

2. Verify Installation:

   • To check if AWS CLI is installed, open your terminal or command prompt and run:

     aws --version
     

   • If installed successfully, you should see the version number displayed. If not, verify that your system's PATH environment variable includes the directory where AWS CLI is installed.

Setting up AWS CLI

1. Configure Your AWS CLI: Run the following command:

   aws configure
   

   This command will prompt you to enter credentials that allow programmatic access to your AWS account.

   • If you're new to AWS, you'll need to create an account. Follow the sign-up process, and once your account is set up, proceed to create an IAM user with programmatic access. After creating the IAM user, run aws configure again to enter the new IAM user's credentials.

   • If you have an existing AWS profile and wish to separate your projects, it's recommended to create a new AWS account and link it to your main account. This can be done via AWS Organizations. Once the new account is ready, create an IAM user in this account and set up a new profile specifically for your project by running:

   aws configure --profile your-new-profile-name
   

   Replace your-new-profile-name with a name relevant to your project. Once you've set up this new profile, you can specify it when running AWS CLI commands by using the --profile option or by setting an environment variable in your terminal session:

   export AWS_PROFILE=your-new-profile-name
   

   This isolates your project's resources and permissions from your other AWS workloads, enhancing security and organization.

2. Verify Configuration: To check if your configuration is correct, try listing your S3 buckets (the command isn't important, it's just checking if everything works):

   aws s3 ls
   

   A successful response confirms that your AWS CLI is set up and ready to use with your AWS account.

Setting Up AWS CDK (Cloud Deployment Kit)

1. Install Node.js and npm AWS CDK is a Node.js application, so you need Node.js and npm (Node.js package manager) installed. You can download and install Node.js and npm from nodejs.org.

2. Install AWS CDK With Node.js and npm installed, you can now install AWS CDK. Run the following command in your terminal:

npm install -g aws-cdk

This installs the AWS CDK globally on your machine, allowing you to use it in any project.

3. Verify CDK Installation After installation, verify that the CDK has been installed correctly by running:

cdk --version

This command will display the installed version of the CDK, confirming that it is ready to use.

Pre-Deployment

Configuring Environment

Okay great! You've got AWS CLI and CDK set up. Now let's setup your project.

First of all, modify the .dotenv.env file to match your project's settings.

• Fill in the Values: Update the .dotenv.env file with your specific project details. Here's what each variable represents:

  • REGION: The AWS region where your resources will be deployed. It's recommended to leave this as us-east-1 unless you have a specific need for another region.
  • PROJECT_BASE_NAME: The base name of your project in the cloud. Avoid using spaces or special characters.
  • DOMAIN_NAME: The name of your domain or your project name. It can have spaces, as shown in the example.
  • DOMAIN: Your domain address. This will be the URL where your project is accessed.
  • DOMAIN_EMAIL: The email address associated with your domain. This will be used for email-related functionalities.
  • S3_BUCKET_NAME: The name of your S3 bucket. Follow AWS's S3 bucket naming conventions (e.g., lowercase letters, no special characters, etc).
  • SQS_EMAIL_PROCESSING_QUEUE_NAME: The name of your SQS queue for processing emails. Keep this as ProcessEmailQueue.
  • SQS_EMAIL_REQUEST_PROCESSING_QUEUE_NAME: The name of your SQS queue for email requests. Keep it as ProcessEmailRequestQueue.
  • PHYSICAL_ADDRESS: The physical address to be included in your emails at the bottom. This is a requirement to comply with anti-spam laws.

• Save the File: After filling in the values, save the .dotenv.env file. This file will be used by your deployment scripts to configure the AWS resources correctly.

Installing Node Modules

Now that your environment is configured, the next step is to install the required Node.js modules. These modules are necessary for the AWS CDK and other project dependencies to function correctly.

1. Navigate to the 'Deployment' Folder: Open your terminal and navigate to the 'deployment' folder within your project directory. Use the cd command to change directories:

   cd path/to/your/project/deployment
   

   Replace path/to/your/project with the actual path to your project's root directory.

2. Run npm Install: In the 'deployment' folder, run the following command to install the required Node.js modules:

   npm install
   

   If you encounter any permission issues, you may need to prefix the command with sudo:

   sudo npm install
   

   This command reads the package.json file in your 'deployment' folder and installs all the dependencies listed there, which is required for ValidateFast to work.

Deployment

Now that we have all the setup, deployment is easy.

1. Prep AWS for CDK deployment by running the following in your deployment folder:

   cdk boostrap
   

2. Once your AWS environment is prepped, run the following script that was provided to you in the boilerplate:

   ./main-deployer.sh
   

   If you run into a permissions error, you can give the script execution access by running the following:

   chmod +x main-deployment.sh
   

   There are some other scripts that are run in the deployment_scripts folder, so you might need to give permissions to those scripts as well:

   cd deployment_scripts
   chmod +x add-sns-topics-to-email.sh
   chmod +x generate-site-constants.sh
   chmod +x get-api-key.sh
   chmod +x sync-email-templates.sh
   chmod +x sync-site-to-s3.sh
   cd ..
   

   After running the script, you should be presented with a table of IAM Policy Changes in which you will be prompted. Simply type y for "yes":

   y
   

Handling Certificate Verification

During deployment, you may encounter a delay where the stack appears to hang. This is typically due to the stack waiting for a domain certificate verification. To resolve this, follow these steps:

1. Certificate Verification:

   • Navigate to the AWS ACM Console.
   • You should see your certificate listed. Under "Domains," there will be two CNAME records.
   • These CNAME records need to be added to your DNS provider.

2. Decision Making for Domain Hosting:

   • Option 1 (Recommended): Allow AWS to host your domain.
     • Update your external DNS nameservers to the values provided in AWS Route 53.
     • In AWS Route 53, click on the hosted zone created by our CDK stack and copy the NS values to your DNS provider.
     • There will be four nameservers to configure.
     • If you have MX records with your previous DNS provider, transfer them to Route 53 by clicking "Create record" and adding the MX record values.
   • Option 2: Use domain forwarding.
     • Add the two CNAME records from ACM to your external DNS provider to verify the certificate.
     • Go to AWS Route 53, click on the hosted zone created by our CDK stack.
     • Forward your domain to the CloudFront distribution's domain name, which can be found in your cdk-outputs.json file under CloudFrontDistributionDomainName. This typically involves setting up an A record that points to the CloudFront distribution.

Website Done!

After changing your nameservers or forwarding your domain to the CloudFront alias A record, your website is ready to go. To check your website:

1. Visit Your Website:
   • Attempt to visit your website by typing its URL directly into your browser.
   • If the site doesn't load immediately, it might be due to DNS nameserver propagation, which can take some time. Wait a few minutes or hours (up to 48 hours) and check again.
   • Alternative Viewing:
     • You can view the live version by entering the address found in your cdk-outputs.json file under "CloudFrontDistributionDomainName".

Configuring Email Sending

While you can now collect emails through your website, additional configuration is required for bulk email sending to all of your subscribers.

Email Identity Verification

1. Check Your Email for Verification:

   • After deployment, AWS SES will send you an email to confirm your email identity.
   • Click the link in the email to complete the verification process.

2. Resend Verification Email (if needed):

   • If you didn't receive the email (possibly due to DNS changes), ensure that you've re-added the email MX records as described previously.
   • Go to the AWS SES Console.
   • If you don't see the verification email, check that you are in the correct AWS region (top right corner next to your account info) that you set up in the dotenv.env file.
   • To resend the verification email, click on "Get set up" in the top left corner. Under "Verify email address," you should see a "Resend email" button.

3. For Different DNS Providers:

   • If you are using an external DNS provider, obtain the CNAME records under "Verify sending domain" and add them to your DNS provider to verify your domain.

4. For AWS Nameservers Users:

   • If it still says "Pending verification," note that it might take time for the DNS changes to propagate.
   • Our boilerplate automatically adds the necessary records to your Route 53 hosted zone, so you may just need to wait.

Requesting Production Access on AWS SES

1. Initiate Production Access Request:

   • Go to the "Get set up" section in the AWS SES console.
   • Click on "Request Production Access."

2. Fill in the Request Form:

   • AWS will inquire about your use of their service to ensure compliance with anti-spam regulations.
   • Provide a concise description of your intended use. For example: "I will be sending emails occasionally to subscribers of an email list. Emails will not be sent with AWS SES unless the user explicitly signs up on the website for the newsletter."

3. Review and Wait for Approval:

   • After submitting your request, your production access status will show as "Under Review."
   • Approval times vary but usually complete within a day, assuming there are no issues.
   • Check the correspondence email provided to AWS for case results.

Final Steps

• Verified!: Once your domain is verified and you have production access, you are ready to send emails. AWS SES pricing is around $1 per 10,000 emails!
• Handling Email Limits: If you anticipate sending more than 50,000 emails per month, contact AWS support to request a limit increase.

This completes the email configuration process, ensuring you can effectively communicate with your subscribers.

Sending an Email

To send an email, a POST request is made to the SendEmailApiEndpoint, which can be found in the cdk-outputs.json file. This request requires an API key generated during the stack deployment.

Retrieving the API Key

1. Generate or Retrieve the API Key:

   • If you need to retrieve the API key, execute the following commands:

     cd deployment_scripts
     ./get-api-key.sh
     

   • The API key will be outputted to your cdk-outputs.json file.

Using the Provided Admin Page

1. Access the Admin Page:

   • We have provided an admin-send-email.html page for sending emails.

   • The actual request is made in /src/js/admin/admin.js.

   • To access the page, visit the following URL, replacing your-domain.com with your actual domain:

     https://your-domain.com/admin-send-email.html
     

   Once you access the page, simply enter your API key, subject, and body, then click submit. Once you click submit (and if all your configurations above have been made), the emails should start going out in batches of 50 to each email that has subscribed to your page.

Creating Your Own Interface

• Custom Interface Option:

  • Alternatively, you may create your own interface for sending emails as per your requirements.

• Generated Constants:

  • ValidateFast will generate constants for your site based on your dotenv.env file everytime you run ./main-deployer.sh. This is located at /site/generated/constants.js. The default behavior applies these constants to your index.html page via /src/js/main/main.js; however you can remove this behavior and hard-code your index.html if you prefer.

Email Templating

• Default Behavior

  • By default, emails will be sent out with the email template located in email_templates, where each of the variables you see in brackets will be filled in with dynamic data. The default variables are provided below:

  {{ subject }}
  {{ body }}
  {{ domain }}
  {{ domain_name }}
  {{ domain_email }}
  {{ physical_address }}
  {{ unsubscribeLink }}
  

• Modifying The Template

  • You can modify this template however you see fit. If you introduce new variables, you will need to send them to the backend as a variable from your frontend, then edit /lib/lambda/sendEmail/index.js to handle the new variable you are sending. Simply add it as a new attribute from requestBody.{attribute} as follows:

  const emailCampaignItemInS3 = {
      id: campaignId,
      templateId: Types.EmailTemplates.GenericEmailTemplate,
      emailClassification: Types.EmailClassification.General,
      attributes: {
          subject: requestBody.subject,
          body: requestBody.body,
          domain: process.env.DOMAIN,
          domain_name: process.env.DOMAIN_NAME,
          domain_email: process.env.DOMAIN_EMAIL,
          physical_address:  process.env.PHYSICAL_ADDRESS
      }
  };
  

  • Note that unsubscribeLink is generated in the helper file in /lib/lambda/shared_layer/emailHelper.cjs.

  Once your changes are made, simply run the deployer again to update the backend:

  ./main-deployer.sh
  

That's it

I know this was quite a bit to go through, but now you have a functioning landing page with email collection / sending capabilities!

This solution allows you to collect and send emails, for essentially rock bottom prices at $1/10,000 emails!

Troubleshooting Guide

Common Issues and Solutions

1. Emails Not Sending via /sendEmail API

If you're encountering issues with email delivery despite a successful API response, consider the following checks and actions:

• Email Identity Not Verified

  • Problem: Your email identity (email address or domain) in AWS SES might not be verified.
  • Solution:
    • Check your verification status in the AWS SES Console.
    • If not verified, look for a verification email from AWS. Follow the link in the email to complete verification. If you didn't receive it, use the "Resend Email" option in the SES console.

• Lack of SES Production Access

  • Problem: You might still be in the AWS SES sandbox environment, which restricts email sending capabilities.
  • Solution:
    • Confirm your access level in the AWS SES Console.
    • If you're in the sandbox, request production access by clicking "Request Production Access." Note: Approval may take several days.

2. API Key and Usage Plan Issues

• Problem: The API key used for the /sendEmail API might be incorrect, expired, or not linked properly to your usage plan.
• Solution:
  • Verify the validity of your API key and check for expiration.
  • Review your usage plan in the AWS API Gateway console to ensure correct configuration.

3. Lambda Function Errors

• Problem: There might be issues within the Lambda function processing the email sending requests.
• Solution:
  • Check AWS CloudWatch logs for the Lambda function to identify any errors or exceptions.

Questions

If you have any questions, feel free to reach out to me on my X handle @realHenryOuang!

Thank you!