How to Build a Mailing List With Ruby on Rails and MailChimp

How to build a mailing list with Ruby on Rails and Mailchimp

Ever needed to collect simple form data from users on a landing page and have a nice UI to show that list on? MailChimp is for you! And here’s how to setup a MailChimp mailing list with Ruby on Rails!

What you’ll need

1. Rails 6 installed
2. Ruby installed. You can follow my article on how to get Rails setup on your machine.
3. A MailChimp account

Initial Setup — Ruby on Rails

1. Create a new rails API using rails new mailing-list-app --api --database=postgresql . Once your rails application is setup, run rails db:create db:migrate to setup your postgres database.
2. In your terminal, run rails s and navigate to http://localhost:3000 to ensure everything is up and running.

Setup — MailChimp

1. Next, create an account with mailchimp. You can also refer to the developer guides here
2. Create an audience (mailchimp uses the word audience interchangeably with mailing list).

Head over to the audience dashboard

5. For the free plan, mailchimp only allows you have one mailing list/audience and to store a maximum of 2000 contacts in that list.

To the left of the dashboard, click the audience button. MailChimp usually already creates an audience list for you once you create an account.

6. We need 3 keys to be able to connect to the MailChimp API from our Rails application. The first key is the unique id. Head to the audience dashboard, click the manage audience > settings. You should see the following box that shows your unique id at the bottom of the page.

Next, in your browser’s address bar, note down the number that comes after the usIn my case, this number was us13. This is the mailchimp data center(dc) that your mailchimp account is connected to.

Finally, we need to get the api key. From the menu navigation, navigate to website > domains > extras and you should see your api key. If you cannot see your api key, click the Create api key button.

Or click here to navigate to the API Keys section in Mailchimp.

Mailchimp API key

Mailchimp by default will only accept first name, last name, phone number and email address from your API. To be able to send more fields from your API to mailchimp, you’ll need to add custom tags in the Mailchimp dashboard.

Still in your audience dashboard, head to All contacts. Then, click on the settings dropdown. Select the Audience fields and *|MERGE|* tags option.

Adding more fields to your mailing list in mailchimp

For our use case, let’s assume the extra field we would like to store about users subscribing to our mailing list is what Company they work for. Click Add field > text, then type the word Company under the label section. Under the merge section, type in COMPANY, in all caps. Click save changes and we should be ready to go.

Adding a company custom tag to your mailing list in mailchimp

Integrating MailChimp and Ruby on Rails

For this tutorial, we’ll send back the response as JSON rather which can then be consumed by your Rails App or any frontend framework you’re using to consume the API.

1. Next, we need to create a controller to receive requests. This controller will call the mailchimp API.

To setup your controller, run the command rails g controller MailingList addUser . This will create a new MailingList controller class in app > controllers > mailing_list_controller. This is where we write the magic!
With our controller setup, we can now setup our routes. Head to config > routes.rb and replace the get mailing_list line with

post '/adduser', to: 'mailing_list#addUser'

2. Let’s install the faraday gem to help us make HTTP requests. In your gem file, add gem 'faraday' to a new line. Save the file. Then run bundle install

3. Now for the code! Inside your MailingListController file, add the following, substituting the appropriate values for your use case.

And there you have it! You can now head to your MailChimp dashboard to see that the users were successfully added to your Audience/list.

Unsubscribing users from the mailing list

MailChimp exposes an additional endpoint to unsubscribe users from a mailing list. For this part, we’ll need to send a MD5 hash of the user’s email address(and not the actual email address string itself). MailChimp identifies users by storing an MD5 hash of their email address.

Let’s get into the code!

We’ll create a new route in our Rails Application that will handle unsubscribing users from the mailing list. In your routes.rb file, add the following route.

put '/removeuser', to: 'mailing_list#removeUser'

Next, we need to add the removeUser method in our controller file — mailing_list_controller.rb. We are using the PUT verb for this route to match what MailChimp expects for the unsubscribe endpoint.

Before writing the code for the removeUser method, we need to require the digest package which is inbuilt in Rails. At the top of your mailing_list controller file, add

require 'digest'

Now, here’s the code that goes into that method. I’ve added code comments for clarity.

Access the full code repo