HOWTO manage Campaign Monitor lists with Ruby

Campaign Monitor is a hosted email marketing service. This guide will show you how to access the Campaign Monitor API with Ruby to manage your Campaign Monitor list subscribers.

Finding your API key

You’ll need your account API key to access the Campaign Monitor API, which you can find in the “Account Settings” page when logged in to your Campaign Monitor account.

For a production app it’s best to store your API key in an environment variable like CAMPAIGN_MONITOR_API_KEY. For development or quick scripting it’ll probably be easier just to paste the API key into your code.

Installing the createsend gem

Add the createsend gem to your Gemfile:

gem 'createsend', '~> 4.0'

Then run bundle. Or install the gem manually with gem install.

The createsend gem is the official Campaign Monitor API client library for Ruby and is more up-to-date than other Campaign Monitor gems.

Finding client & list identifiers

Subscriber lists are tied to clients (in the customer sense of the word, not the computing sense). To find the identifier for a subscriber list you can enumerate the clients and the subscriber lists associated with each client. For example:

require 'createsend'

auth = {api_key: ENV.fetch('CAMPAIGN_MONITOR_API_KEY')}

createsend = CreateSend::CreateSend.new(auth)

createsend.clients.each do |item|
  client_name = item.Name

  client = CreateSend::Client.new(auth, item.ClientID)

  client.lists.each do |item|
    puts "#{item.ListID} #{client_name} #{item.Name}"
  end
end

Typically you’ll want to script this manually and then store the identifiers of the lists you care about together with the API key, or just hard-coded into your application code.

For more advanced use cases it might instead be more appropriate to load and store a mapping of the list identifiers on application initialization.

Adding a subscriber

Call the CreateSend::Subscriber.add method to subscribe a user to a list:

require 'createsend'

auth = {api_key: ENV.fetch('CAMPAIGN_MONITOR_API_KEY')}

list_id = '9be0d1416f6508df452371506f3c547b'

email, name = 'alice@example.com', 'Alice'

begin
  CreateSend::Subscriber.add(auth, list_id, email, name, [], false)
rescue CreateSend::BadRequest => exception
  fail "could not add #{email} code=#{exception.data.Code}"
end

The list_id is the identifier of the list you want to add the subscriber to.

The last parameter to the .add method controls the resubscribe behaviour: whether or not a user will be re-subscribed to the list if they have previously unsubscribed.

Remember to rescue from CreateSend::BadRequest and check the exception code to handle errors like invalid email addresses. The adding a subscriber documentation includes a list of all the possible error codes.

Want to add a group of subscribers in a single request? Sign-up below to learn how to batch import subscribers into your list.

Unsubscribing a subscriber

Call the CreateSend::Subscriber#unsubscribe method to unsubscribe a user from a list:

require 'createsend'

auth = {api_key: ENV.fetch('CAMPAIGN_MONITOR_API_KEY')}

list_id = '9be0d1416f6508df452371506f3c547b'

email = 'alice@example.com'

begin
  CreateSend::Subscriber.new(auth, list_id, email).unsubscribe
rescue CreateSend::BadRequest => exception
  fail "could not unsubscribe #{email} code=#{exception.data.Code}"
end

The unsubscribe call is implemented as an instance method instead of a class method.

The list_id is the identifier of the list you want to remove the subscriber from.

Remember to rescue from CreateSend::BadRequest and check the exception code to handle errors like invalid email addresses. The unsubscribing a subscriber documentation includes a list of all the possible error codes.

Updating custom fields

Campaign Monitor supports storing additional data about subscribers which can then be used to segment lists and send more targeted emails. Useful for Serious Business™.

Call the CreateSend::Subscriber#update method to set custom fields for a subscriber:

require 'createsend'

auth = {api_key: ENV.fetch('CAMPAIGN_MONITOR_API_KEY')}

list_id = '9be0d1416f6508df452371506f3c547b'

email = 'alice@example.com'

custom_fields = [{'Key' => 'Last Order Date', 'Value' => Date.today}]

begin
  subscriber = CreateSend::Subscriber.new(auth, list_id, email)

  subscriber.update(nil, nil, custom_fields, false)
rescue CreateSend::BadRequest => exception
  fail "could not update #{email} code=#{exception.data.Code}"
end

Custom field data is structured as an array of hashes with 'Key' and 'Value' keys. If you are getting CreateSend::BadRequest exceptions with a 400 error code then check to make sure you haven’t passed a hash instead.

Make sure to add the necessary custom fields and their types that you want to use beforehand in the Campaign Monitor list settings. If you include fields that haven’t been added the data will be silently ignored.

Want to add a group of subscribers in a single request for better efficiency and quicker imports? Sign-up below and learn how to batch import subscribers into your list.