How I built a free newsletter referral system for EmailOctopus in an hour

I am using EmailOctopus for my newsletter ARK Watcher ( and I love it. It allowed me to scale up to first 2500 subscribers for free and being able to connect AWS SES (Simple Email Service) to send up to 62,000 emails for free every month was essential for a daily newsletter like mine. And don’t get me started with their world class customer service! You can check them out here (disclaimer: referral link):

But, unlike Mailchimp and Convertkit, EmailOctopus does not have a robust ecosystem of solutions to support subscriber engagement activities as you scale up. One of the most important ways of organically growing your subscriber base is through a referral program and as far as I know, I do not know of any solution to date that easily integrates with EmailOctopus.

Now there are myriad of solutions out there for integrating referral system for newsletters but most have bells and whistles that you probably don’t need at this point and don’t offer any “free till you become legitimate newsletter” plan.

Here is a list of companies offering referral system integration and their pricing (as of 12/25/2020):

Sparkloop (

  • Lowest Tier Price: $29/month
  • Easy Integration with EmailOctopus: No

Viral Loops (

  • Lowest Tier Price: $34/month (can try for free for 14 days for up to 100 participants)
  • Easy Integration with EmailOctopus: No

Referral Hero (

  • Lowest Tier Price: $49/month (can try for free for 14 days)
  • Easy Integration with EmailOctopus: No

GrowSurf (

  • Lowest Tier Price: Free! (for 500 participants)
  • Easy Integration with EmailOctopus: No

So being the cheapskate and lazy maker I am, I decided to just roll with my own solution that I can build under an hour and not maintain ever.

Here are requirements to get started:

  1. You know how to code a bit. Knowing Javascript is necessary for later part of the implementation.
  2. AWS account — you can signup for free at
  3. EmailOctopus account (not sure why you don’t have this yet but) — you can signup for free at (disclaimer: referral link)
  4. And that’s it!

Now let’s get started.

  1. Add a new numerical custom field to your EmailOctopus list contacts:
I named mine “Referred” but You can name your field anything. Just remember what you named it for later.

Also, take a note of what your list unique id is by looking at the url:{list id}

2. Add {{ID}} merge tag to your referral link. This will merge in EmailOctopus’s unique contact Id. I’ve updated my Facebook, Twitter and email button with the link with ID merge tag as well. Here is an example:

3. Create your EmailOctopus API key

Keep the API key copied for later.

4. Install Serverless on your local terminal and setup your project by following instructions here:

npm install serverless -gserverless install -u -n  aws-python-simple-http-endpointnpm install --save serverless-python-requirements

*** I chose python as my language as I built all my backend with python but you are more than welcome to use any of supported languages by AWS Lambda. ***

5. Update file like so:

6. Update serverless.yml file and insert your credentials:

*** If you don’t have your AWS profile setup separately like I have, you can remove profile key and use your default one. ***

7. Add requirements.txt file:

8. Deploy the function and take a note of the route url:

serverless deploy

9. On your landing page, add a click event bind (target.addEventListener()) to the subscribe button with function that does following:

  1. Detects that url path has id params
  2. If id params exists, make a AJAX GET request to Serverless function url deployed in #8 with the id as route params.

My landing page is implemented is vanilla VueJS and probably won’t be relevant for most readers but here is an example:

Detect id params on document load
Subscribe button with click event bind
Click event bound method with url to Serverless function

If all things are setup correctly, you should see this once your subscribers start sending referrals to their friends and they subscribe:

Now you can setup a segment with contacts over a specified referred count. I set mine up for greater than equal to 3:

Let me know if you have any questions down below and if you are interested in my newsletter or just want to show me some ❤️, you can subscribe here:

Cheapskate maker, stitching free products and services together. Digital settler. Engineer @ Rentapplication

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store