Listmonk - Developer Guide

Welcome to our comprehensive developer guide for deploying Listmonk on AWS! Listmonk is a powerful, open-source email marketing platform, and with our pre-configured AMI, you can get it running in your own AWS environment in minutes.

This guide will walk you through every step, from launching the AMI to configuring your domain and securing your instance. Let's get started!

Related Article

How to Install Listmonk on AWS by Single Click | Commercial Support for Listmonk

Effortlessly deploy Listmonk, a top email marketing platform, on your self-hosted server at low cost with our pre-configured AMI, ideal for businesses in the UK, USA, Europe, Ireland, Singapore, and Thailand seeking efficient marketing solutions.

Meetrix.IO • Kelum Sampath

Launching the Listmonk AMI from AWS Marketplace

Step 1: Subscribe to the AMI

1. Navigate to the Listmonk listing in the AWS Marketplace.
2. Click the Continue to Subscribe button.
3. Accept the terms and conditions by clicking Accept Terms.
4. After a brief processing period, click Continue to Configuration.

Step 2: Configure and Launch

1. On the "Configure this software" page, select your desired AWS region.
2. Click Continue to Launch.
3. From the "Choose Action" dropdown, select Launch CloudFormation.
4. Click Launch. This will redirect you to the CloudFormation console to create a new stack.

Deploying with CloudFormation

Step 1: Create Stack

1. You'll be taken to the "Create stack" page. Ensure the "Template is ready" option is selected.
2. Click Next.

Step 2: Specify Stack Details

Provide the necessary parameters for your Listmonk deployment. These settings define how your instance will be configured.

After filling in the details, click Next.

Step 3: Configure Stack Options

1. Under "Stack failure options," choose Roll back all stack resources. This ensures that failed deployments are automatically cleaned up.
2. Click Next.

Step 4: Review and Submit

1. Review all the details you've entered.

2. Acknowledge that CloudFormation might create IAM resources by ticking the checkbox.

3. Click Submit to start the deployment.

You will be redirected to the CloudFormation stacks page, where you can monitor the deployment progress.

The stack creation process typically takes 5-10 minutes. Wait for the status to change to CREATE_COMPLETE.

Configuring Your DNS

Step 1: Get the Public IP Address

Once the stack is created, go to the Outputs tab and copy the value of PublicIp.

Step 2: Create a DNS Record

1. Go to your DNS provider (e.g., AWS Route 53, GoDaddy, Cloudflare).
2. Create an A record for your domain (e.g., listmonk.yourdomain.com).

3. Point the record to the PublicIp you copied in the previous step.
4. Save the record.

Accessing Your Listmonk Instance

You can now access your Listmonk application using the DashboardUrlIp from the CloudFormation "Outputs" tab.

502 Bad Gateway Error?

If you see a "502 Bad Gateway" error, don't worry! The application is likely still starting up. Please wait about 5 minutes and then refresh the page.

1. Click "Login" button and enter details.

2. Then click continue button. You will navigate to the Listmonk dashboard.

3. Before you start, please go to the "General" tab in the settings and modify the "Root URL" to correspond with your domain. Additionally, adjust the "Default `from` email" according to your preference, then click on "Save".

Setup Gmail SMTP server

Step 1: Obtain password

1. Navigate to your google account https://myaccount.google.com/.
2. In the Security section, enable 2-step verification.

3. Use the search bar to find the "App passwords" option and navigate to the "App passwords" section.

4. Provide an app name and click on "create" to generate.

5. Once generated, copy the password and ensure to keep it safe as it will not be visible again.

Step 2: Test SMTP

1. Navigate to the SMTP tab in the Listmonk "Settings".
2. Provide the following details:
   • Host: smtp.gmail.com
   • Port: 465
   • Auth protocol: LOGIN
   • Username: Your Gmail address
   • Password: Previously generated password
   • To e-mail: An email address to which you want to send the test email
   
3. Click on "Send Email". If everything is in order, you will receive a test email.

4. Save the settings, and you're all set to proceed.

Manual SSL Certificate Generation

If your domain is not hosted on Route 53, the automatic SSL setup might fail. In that case, you'll need to generate the certificate manually.

Step 1: SSH into the Server

1. From the CloudFormation "Outputs" tab, copy the PublicIp.

2. Open your terminal and use the following command to connect to the server. Replace your-key.pem with your key pair file.

ssh -i "your-key.pem" ubuntu@<Public IP address>

Step 2: Run the Certificate Script

Once logged in, run the following script. It will prompt you to enter your domain name and email address.

sudo /root/certificate_generate_standalone.sh

Managing Your Listmonk Instance

Shutting Down and Restarting

1. In the CloudFormation stack's Resources tab, click the link for the Instance to go to the EC2 console.

2. Select the instance and use the Instance state dropdown to Stop instance or Start instance.

Removing the Deployment

To completely remove the Listmonk application and all associated resources, simply delete the CloudFormation stack from the AWS console.

API Documentation

Listmonk provides a powerful REST API that allows you to control the entire platform programmatically. You can find the complete documentation here:

Official Listmonk API Documentation

Upgrading Your Instance

We regularly update our AMI with the latest version of Listmonk. To upgrade, you can launch a new instance with the newer version and migrate your data. Remember to back up your server data before removing the old instance.

Troubleshooting Common Issues

1. vCPU Quota Error: If you see an error about vCPU limits, please follow this guide to request an increase.

2. Insufficient Capacity: If you get an "insufficient instance capacity" error, try launching the stack in a different AWS region or at a later time.

3. Dashboard Error on First Load: If the dashboard doesn't load immediately, wait 5-10 minutes for the services to initialize and then try again.

Conclusion

To sum up, Listmonk proves to be a versatile solution for managing mailing lists and newsletters, featuring a self-hosted model with minimal dependencies—it operates as a standalone binary with only a Postgres database required. This setup ensures users have full control over their email marketing processes, enabling seamless integration and scalability without reliance on external services. Whether for small businesses or large enterprises, Listmonk offers robust features and straightforward deployment, making it an excellent choice for enhancing and managing email campaigns effectively. Opt for Listmonk to streamline your email marketing efforts with ease and control.

Technical Support

If you run into any issues, our support team is here to help. Reach out to us at aws@meetrix.io.