Around 2020 I began writing a weekly e-mail newsletter to keep the Code for Boston community informed of our latest happenings. After doing this for a year and half I started to realize that the content in the newsletter could also be great if provided…on a website! However I did not want to do double the amount of work. Additionally the MailChimp platform has been a pain point in publishing the newsletter. It is fairly well designed for novice users who are creating novel emails every time they login. However the user interface becomes repetitive and somewhat of a hinderance in situations where you are sending a template email with different content on a weekly basis. I wanted to streamline this process to reduce the time I needed to spend on newsletter content publishing every week.
Code for Boston currently uses a Jekyll website hosted on GitHub Pages. This has many advantages including minimizing the amount of work to maintain it. The disadvantage is it lacks an interface that is friendly for non-developers. However this is not a barrier for our organization which is flush with software development talent. I worked with Code for Boston Leadership Team member Brian Sanders who developed a GitHub Action to automatically publish a newsletter based off the Markdown file added to our website’s blog posts folder.
Code for Boston newsletters now begin their life as a markdown file created in iA Writer:
Folks that want to duplicate this process can of course use an editor of their choice.
Once I write the post in Markdown, I commit and upload it to the codeforboston.org GitHub repo. This kicks off two actions:
- Publishing the update to the website’s Latest Updates section.
- Sending a request to SendGrid to create a Single Send of the email to our subscribers using their API.
We will be re-testing this feature next week with a plan to cut over and launch it the week after!
A few things we learned:
- Front-end work on email newsletter templates can be a bit annoying. Porting the template we were using from MailChimp to SendGrid required a bit more effort than we expected, but it was worth it to maintain the design that we liked otherwise and keep consistent with what our subscribers are used to receiving.
- GitHub Actions can be a little finicky to develop with. Brian was able to write most of the fundamentals of the process fairly easily, but we have been debugging various issues over the past month or two. Today we just fixed the fact it couldn’t find the post in the repo by removing an id key from one of the steps. We don’t know why it fixed it, but we know it is now working.
SendGrid itself has been pretty good to work with. It has a useful preview feature and most of the features you would want for sending a newsletter as a software developer. The only annoyance is if you want to “share” an account you have to use two-factor authentication with a phone or their authy app so it is difficult to do that.
After we finalize this work we’re happy to make the action available to other brigades, or if you’re ambitious just peruse our GitHub repo.