Subscribe
3 min read

Using GCTools with Ghost on Reclaim Cloud

A somewhat quick "here are my notes" style blog post, that turned out to be longer than I would have expected!

Today I needed to do some work with bulk user management of folks on https://blog.reclaimhosting.com/ as we re-organize our newsletter offerings there. Ghost has excellent built-in tools for importing and exporting member lists via CSV, and can do things like add labels to users on import (and is smart enough not to add duplicate people on import), which is nice, but it doesn't have a way I could find to subscribe a list of people to a new newsletter, in bulk.

Here's an overview of how I worked around that:

  1. Import a CSV of the folks who should be on the list. In this case, it was just a single column CSV (I guess technically there were no commas separating values here because it was one column 😆).
  2. Use the label feature on import to give those people a unique label in the member list.
  3. Use GCTools to add folks with a particular label to a particular newsletter using its add-member-newsletter-subscription option.

I'm not going to write up instructions for everything here, but I did want to document how to install and use GCTools.

Installing GCTools

GCTools is handy, and I used it as part of my process to move this blog from hugo to its current home on Ghost, but I don't otherwise have a ton of experience with it. It's designed to be a handy command line interface for the Ghost API. Because it talks to Ghost using its API, it doesn't technically need to be installed on the same server or environment as where you host Ghost. That being said, I feel like it's convenient to do so when working with Ghost on Reclaim Cloud that way I don't have to install it on my local machine.

GCTools requires NodeJS, and the Yarn package manager, so it took me a few minutes to brush up on how to install the appropriate version of those, but here is the whole process. Start by opening the terminal for your Ghost environment on Reclaim Cloud, then run these commands:

# Install NodeJS and NPM
dnf module install nodejs

# Install Yarn
npm install --global yarn

# Clone the git repo for GCTools
git clone https://github.com/TryGhost/gctools

# Use yarn to install the dependencies for GCTools
cd gctools
yarn

# Make the gctools command accessible globally
npm link

Then you can check that everything installed successfully by just running gctools.

Using GCTools to add members to a newsletter in bulk

This is the sample command in GCTools's README to do this:

gctools add-member-newsletter-subscription <apiURL> <adminAPIKey> <newsletterID> --onlyForLabelSlugs 'premium-blog,news'
  • <apiURL> should just be your blog's URL
  • An <adminAPIKey> can be created in Ghost's settings under Advanced > Integrations > Custom
  • The <newsletterID> can be found by going to Ghost's settings and editing a Newsletter. The ID is a bunch of characters at the end of the URL.
A screenshot of the Ghost admin interface's newsletters edit screen. The URL has a random string of 24 characters at the end of the URL highlighted.
No, that's not a real Newsletter ID.
  • Finally, you'll want to replace premium-blog,news with a comma separated list of the "label slugs" to use. These slugs can be found by filtering for the label on the members page, clicking Apply Filters, then checking the URL.
A screenshot of the Ghost admin interface's member page with the list of members filtered. The text "test" is underlined in the URL.
They are generally similar to the label name with special characters replaced, so if you have a simple label name you can probably just guess it.

Then I ran the command (with a real API key and newsletter ID):

gctools add-member-newsletter-subscription https://blog.reclaimhosting.com <myapikeywouldbehere!> <mynewsletteridwouldbehere!> --onlyForLabelSlugs 'test'
A screenshot of the terminal output of the gctools command. It sucesfully added 65 members!
🎉

Comments