Sign in Subscribe
PaaS Products

Listmonk - Developer Guide

dinesh chathuranga

• 7 min read
Listmonk - Developer Guide

Listmonk is a self-hosted powerhouse for newsletters and mailing lists. Experience seamless email campaigns with a built-in feature to auto-push PostgreSQL backups to S3 daily.

Video
Blog
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:
Meetix.IOKelum Sampath

Prerequisites

Before you get started with the Listmonk AMI, ensure you have the following prerequisites:

Launching the AMI

Step 1: Find and Select 'Listmonk' AMI

  1. Log in to your AWS Management Console.
  2. Navigate to the "Listmonk" in  AWS Marketplace.

Step 2:  Initial Setup & Configuration

  1. Click the "Continue to Subscribe" button.
  2. After subscribing, you will need to accept the terms and conditions. Click on "Accept Terms" to proceed.
  3. Please wait for a few minutes while the processing takes place. Once it's completed, click on "Continue to Configuration".
  4. Select your preferred region in "Configure this software" page and click "Continue to Launch" button.
  5. From the "Choose Action" dropdown menu in "Launch this software" page, select "Launch CloudFormation" and click "Launch" button.

Create CloudFormation Stack

Step1: Create stack

  1. Ensure the "Template is ready" radio button is selected under "Prepare template".

2. Click "Next".

Step2: Specify stack options

  1. Provide a unique "Stack name".
  2. Provide the "Admin Email" for SSL generation.
  3. For "DeploymentName", enter a name of your choice.
  4. Provide a public domain name for "DomainName". (Listmonk will automatically try to setup SSL based on provided domain name, if that domain hosted on Route53. Please make sure your domain name hosted on route53. If its unsuccessful then you have to setup SSL manually)
  5. Choose an instance type, "InstanceType" (Recommended: t3.medium).
  6. Select your preferred "keyName" (Name of an existing EC2 key pair for SSH access to the EC2 instance).
  7. Enter a strong password for "ListmonkPassword" (Password for listmonk Web interface).
  8. Provide a S3 bucket name to "S3Bucket" for storing PostgreSQL backups.
  9. Set "SSHLocation" as "0.0.0.0/0".
  10. Keep "SubnetCidrBlock" as "10.0.0.0/24".
  11. Keep "VpcCidrBlock" as "10.0.0.0/16".
  12. Click "Next".

Step3: Configure stack options

  1. Under "Stack failure options", select "Roll back all stack resources".
  2. click "Next".

Step4: Review

  1. Review and verify the details you've entered.

2. Tick the box that says, "I acknowledge that AWS CloudFormation might create IAM resources with custom names".

3. Click "Submit".

Afterward, you'll be directed to the CloudFormation stacks page. You can easily locate the corresponding stack by searching for the stack name you entered in Step2.

Please wait for 5-10 minutes until the stack has been successfully created. Afterward, you can click the "Refresh" button under the "Stacks" section.

Update DNS

Step1: Copy IP Address

  1. Copy the public Ip labeled "PublicIp" in the "Outputs" tab.

Step2: Update DNS

  1. Go to AWS Route 53 and navigate to "Hosted Zones".
  2. From there, select the domain you provided to "DomainName".

3. Click "Edit record" in the "Record details" and then paste the copied "PublicIp" into the "value" textbox.

4. Click "Save".

Access Listmonk Dashboard

  1. you can access the Listmonk application through the "DashboardUrl" provided in the "Outputs" tab.

(If you encounter a "502 Bad Gateway error", please wait for about 5 minutes before refreshing the page)

2. Click "Login" button and enter "listmonk" as the username. For the password, use the "ListmonkPassword" that you entered in the "Step 2: Specify stack options" under the "Create CloudFormation Stack" section.

3. Then click "Sign In" to proceed. You will navigate to the Listmonk dashboard.

4. 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

Step1: 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.

Step2: 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.

Generate SSL Manually

Listmonk will automatically try to setup SSL based on provided domain name, if that domain hosted on Route53. If its unsuccessful then you have to setup SSL manually.

Step1: Copy IP Address

  1. Proceed with the instructions outlined in the above "Update DNS" section, if you have not already done so.

2. Copy the Public IP address indicated as "PublicIp" in the "Outputs" tab.

Step2: Log in to the server

  1. Open the terminal and go to the directory where your private key is located.
  2. Paste the following command into your terminal and press Enter: ssh -i <your key name> ubuntu@<Public IP address>.

3. Type "yes" and press Enter. This will log you into the server.

Step3: Generate SSL

Paste the following command into your terminal and press Enter and follow the instructions:

sudo /root/certificate_generate_standalone.sh

Admin Email is acquiring for generate SSL certificates.

Shutting Down Listmonk

  1. Click the link labeled "Instance" in the "Resources" tab to access the EC2 instance, you will be directed to the Listmonk instance in EC2.

2. Select the listmonk instance by marking the checkbox and click "Stop instance" from the "Instance state" dropdown. You can restart the instance at your convenience by selecting "Start instance".

Remove Listmonk

Delete the stack that has been created in the AWS Management Console under 'CloudFormation Stacks' by clicking the 'Delete' button.

API Documentation

All features that are available on the listmonk dashboard are also available as REST-like HTTP APIs that can be interacted with directly. Request and response bodies are JSON. This allows easy scripting of listmonk and integration with other systems, for instance, synchronisation with external subscriber databases.

API requests require BasicAuth authentication with the admin credentials.

  • username: listmonk
  • password: "ListmonkPassword" that you entered in the "Step 2: Specify stack options" under the "Create CloudFormation Stack" section.

API / Subscribers

API / Lists

API / Import

API / Campaigns

API / Media

API / Templates

API / Transactional

Upgrades

When there is an upgrade, we will update the product with a newer version. You can check the product version in AWS Marketplace. If a newer version is available, you can remove the previous version and launch the product again using the newer version. Remember to backup the necessary server data before removing.

Troubleshoot

  1.  If you face the following error, please follow https://meetrix.io/articles/how-to-increase-aws-quota/ blog to increase vCPU quota.

2.  If you face the following error (do not have sufficient <instance_type> capacity...) while creating the stack, try changing the region or try creating the stack at a later time.

3. If you face the below error, when you try to access the API dashboard, please wait 5-10 minutes and then try.

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

Reach out to Meetrix Support (support@meetrix.io)  for assistance with Listmonk issues.

Discover Seamless Meetings with >>>
Meetrix