Subscribing and Sending Campaign using Mailchimp 3.0 API
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
- Gibbon Github Page
- Creating and sending a campaign from rails
- Create and send a Mailchimp campaign with gibbon, using content sections from ActionView templates Raw
- Send a Campaign
Related Articles