Building an audience for your blog and keeping it engaged is hard. Instead of crossing your fingers and waiting for your visitors to come back, you can invite them to keep in touch by receiving a newsletter. For Ruby on Rails blogs, there is newsletter engine Maktoub. For everything else, there is Mailchimp. And when you want to have the bare minimum, there is Correole. Correole consists of a web API for subscribe + unsubscribe and a command for sending the newsletter. The newsletter is composed automatically from the RSS feed of your blog and a configurable template.
Features are subscribe, unsubscribe, send, and purge.
Subscribes happen via a form in your site. Take for example the subscription form in this blog. The subscription form consists of a textbox and a button. The form asks to enter an email address and the button submits the address to the subscribe endpoint. The script that submits the address is the following.
Transmission of the email address happens by means of SSL, so the address is kept private during transmission to Correole.
Unsubscribes happen via a link you include in your newsletter, like the following.
For email address firstname.lastname@example.org, the URL of the link is the following.
When the user opens the link in their browser, Correole unsubscribes them and issues a redirect to a confirmation page of your choice, ideally a page in your website with a style that is consistent with the rest of your site, like the following.
Submission of newsletter happens on request via command
Correole does best-effort delivery.
When you execute
correole send, tries to send the
newsletter to each subscriber and does not retry or record failures.
correole send is ideal for use in Heroku
scheduler, so that
you concentrate in writting content.
When you execute
correole send, Correole automatically composes an
email from new RSS items and the configured templates. Each email is
multipart, so you know your readers will receive your newsletter just
like you intended. Templates for html and plain text are configurable
ERB templates. For example, the default HTML template is the
The variables that are available in HTML and plain templates are the following.
title. Title of your RSS feed.
unsent_items. List of RSS items that are new. Each item consists of following properties.
item.link. The link of the item.
DateTimeobject corresponding to the timestamp of the item.
item.description. The description of the item.
sent_items. List of RSS items that are given by the RSS feed and are not new. Each item consists of the same properties as the items in list
unsubscribe_uri. URI of the unsubscribe endpoint for a given user.
The first time you run the newsletter, you may want to omit items that
are too old. You can skip new items by means of command
purge. For example, before sending out the first newsletter I ran
correole purge like so.
Try it yourself in Heroku
Correole is possible thanks to the wonderful libraries and services it uses.
The following are features that I may or may not implement.
- Newsletter archive. Record the messages that Correole has sent.
- Retry failed submit. For each subscriber, record the newsletters that have been submitted and the ones that have failed. Retry those that failed a given number of times.
- Send one-off messages. When you want to share exclusive content with your subscribers, a one-off message is the way to go.
Would you like to contribute? Submit a pull request with tests following these guidelines.
Correole is released under MIT license, so you fork the project and use it in your propietary application.
Want to read more?
I love to explain and answer questions on programming problems. I publish a new programming problem and its solution every month. Did I mention that I love to answer questions?