Subscribing and Sending Campaign using Mailchimp 3.0 API

By

In this article, we will discuss how to use Mailchimp API version 3.0 using Gibbon version 3.1. You can install the gem.

Setup and Configuration

gem install gibbon

For Rails app, you can add it to Gemfile and run bundle. Set the configuration values globally in app/config/initializers/gibbon.rb:

Gibbon::Request.api_key = "your_api_key"
Gibbon::Request.timeout = 15
Gibbon::Request.open_timeout = 15
Gibbon::Request.symbolize_keys = true
Gibbon::Request.debug = false

Subscriber to Mailing List

To subscribe a member to a list:

gibbon.lists(list_id).members.create(body: {email_address: "foo@bar.com", status: "subscribed", merge_fields: {FNAME: "Bugs", LNAME: "Bunny"}})

The list_id is the Mailchimp mailing list id. You can find the value by logging in to your Mailchimp account. The values for email, FNAME & LNAME will come from form values when someone subscribes to your mailing list.

Create and Send a Campaign

Figuring out this part was tricky. The gibbon readme on github is not clear. I wanted to send a plain text email to my subscribers. The sample code I found on github issues for gibbon showed how to use template for the email body. I did not need any template. Reading the source of gibbon and the specs did not show how a client could use Gibbon API to create a campaign and send emails. I read the developer docs for Mailchimp. Create a new campaign has the following required fields:

type (regular, plaintext, etc ...)
recipients
settings

Here is a sample request from the docs:

curl --request POST \
--url 'https://usX.api.mailchimp.com/3.0/campaigns' \
--user 'your-mailchimp-apikey' \
--header 'content-type: application/json' \
--data '{"recipients":{"list_id":"your-mailchimp-subscriber-list-id"},"type":"plaintext","settings":{"subject_line":"Email Subject","reply_to":"feedback@rubyplus.com","from_name":"Bala Paranj"}}' \
--include

Now we need to map the curl sample request to Gibbon request. Let's first format the data section of the curl request.

{
    "recipients": {
        "list_id": "your-mailchimp-subscriber-list-id"
    },
    "type": "plaintext",
    "settings": {
        "subject_line": "Email Subject",
        "reply_to": "feedback@rubyplus.com",
        "from_name": "Bala Paranj"
    }
}

Now we have all the required fields to create a campaign. We can create the hash required to make the call using Gibbon.

create_campaign_request = {
  type: "plaintext",
  recipients: {
    list_id: 'mailchimp list_id goes here',
  },
  settings: {
    subject_line: 'Email Subject',
    title: 'August 10,2017 Newsletter',
    from_name: 'Bala Paranj',
    reply_to: 'feedback@rubyplus.com',
  }
}

We can now make the curl equivalent call in Ruby:

gibbon = MailList::GibbonApi.new
gibbon.api.campaigns.create(body: create_campaign_request)

The focus question for our next unknown : How do we provide the text content as the body of the email? The readme, specs and source code of gibbon gives us no clue. One of the closed tickets gives us a clue:

gibbon.api.campaigns(campaign_id_from_create_results).content.upsert(body: email_body)

The email body is a hash:

email_body = {
  template: {
    id: 'xyz123'
  }
}

I was not using any template. What is the email body for a text email? Search for this focus question led to campaign content. The response showed:

{
  "plain_text": "** Designing Your Email blah blah blah"
}

The Mailchimp API has nothing related to how we can set the body of the email for a plain text email. We have two options. Test this:

email_body = { content: 'Just a wild guess' }

and 

email_body = { plain_text: 'Just a wild guess' }

If this does not work, create a ticket on gibbon home page and send email mailchimp support.

References

Related Articles

Create your own user feedback survey