MailChimp3

mailchimp3 is a Rubygem that provides a very thin, simple wrapper around the MailChimp RESTful JSON "Marketing" API version 3 documented at mailchimp.com/developer/marketing/api.

This wrapper is very low-level -- you'll still be dealing with individual GET, POST, PATCH, and DELETE requests, but the gem handles the OAuth2 flow (getting a token), passing the auth token in every request, and raises descriptive errors you can easily rescue in your own code.

gem install mailchimp3

1. Set your HTTP Basic auth key somewhere in your app (probably an initializer if using Rails):

   MailChimp3.config.basic_auth_key = 'key-us2'

2. Create a new API object and use it:

   # HTTP Basic
   api = MailChimp3.new

3. Call a method on the api object to build the endpoint path.

   api.lists
   # /lists

4. For IDs, treat the object like a hash (use square brackets).

   api.lists['abc123'].members
   # /lists/abc123/members

5. To execute the request, use get, post, patch, or delete, optionally passing arguments.

   api.lists.get(count: 25)
   # GET /lists?count=25
   api.lists['abc123'].members['cde345'].get
   # GET /lists/abc123/members/cde345

1. Set your OAuth client id and secret somewhere in your app (probably an initializer if using Rails):

   MailChimp3.config.client_id = 'abc123'
   MailChimp3.config.client_secret = 'xyz456'

2. (First time for each user) Get an OAuth 2 token by calling MailChimp3.oauth.authorize_url and redirect your user to it:

   url = MailChimp3.oauth.authorize_url(
     redirect_uri: 'http://example.com/oauth/callback'
   )
   redirect_to url

3. Upon redirect back to your app (in your /oauth/callback action), call MailChimp3.oauth.complete_auth, passing in the code param and the redirect_uri again.

   data = MailChimp3.oauth.complete_auth(
     params[:code],
     redirect_uri: 'http://example.com/oauth/callback'
   )

   The hash returned looks like this:

   {
     token: <OAuth2::AccessToken>
     token_string: 'abc123',
     metadata: {
       dc: 'us2'
     }
   }

   Then get the authentication token and data center, and store it on your user record for later use:

   user.update_attributes(
     mailchimp_auth_token: data[:token_string],
     mailchimp_data_center: data[:metadata][:dc]
   )

4. (Subsequent times for user) Instantiate the api object, passing in the auth token and data center:

   api = MailChimp3.new(
     oauth_access_token: user.mailchimp_auth_token,
     dc: user.mailchimp_data_center
   )

5. Use the api instance to make API calls!

require 'mailchimp3'

api = MailChimp3.new(basic_auth_key: 'abc123abc123abc123abc123abc123ab-us2')
api.lists.post(
  name: 'Church.IO',
  email_type_option: false,
  permission_reminder: 'signed up on https://church.io'
  contact: {
    company: 'TJRM',
    address1: '123 N. Main',
    city: 'Tulsa',
    state: 'OK',
    zip: '74137',
    country: 'US'
  },
  campaign_defaults: {
    from_name: 'Tim Morgan',
    from_email: 'tim@timmorgan.org',
    subject: 'Hello World',
    language: 'English'
  },
)

...which returns something like:

{
  "id"   => "abc123abc1",
  "name" => "Church.IO",
  "contact" => {
    "company"  => "TJRM",
    "address1" => "123 N. Main",
    "address2" => "",
    "city"     => "Tulsa",
    "state"    => "OK",
    "zip"      => "74137",
    "country"  => "US",
    "phone"    => ""
  },
  "campaign_defaults" => {
    "from_name"  => "Tim Morgan",
    "from_email" => "tim@timmorgan.org",
    "subject"    => "test",
    "language"   => "English"
  },
  # ...
  "stats" => {
    "member_count" => 0,
    # ...
  },
  "_links" => [
    {
      "rel"          => "self",
      "href"         => "https://us2.api.mailchimp.com/3.0/lists/abc123abc1",
      "method"       => "GET",
      "targetSchema" => "https://us2.api.mailchimp.com/schema/3.0/Lists/Instance.json"
    },
    # ...
  ]
}

Anything you append to the end gets handled by method_missing and returns a new Endpoint object. This is what allows this gem work with any endpoint without the library code needing to be updated.

Similar to the method_missing above, endpoint['whatever'] and endpoint[123] are handled dynamically, which allows you to build endpoints containing numbers, hyphens, or other characters not allowed by a Ruby method name.

get() works for a collection (index) and a single resource (show).

# collection
api.lists['abc123'].members.get(count: 25)
# => { members: array_of_resources }

# single resource
api.lists['abc123'].members['cde345'].get
# => resource_hash

If the endpoint accepts parameters, you can pass them in the params hash.

post() sends a POST request to create a new resource.

api.lists['abc123'].members.post(...)
# => resource_hash

The parameter given is sent as the body of the request. See Example above.

patch() sends a PATCH request to update an existing resource.

api.lists['abc123'].members['cde345'].patch(...)
# => resource_hash

The parameter given is sent as the body of the request. See Example above.

delete() sends a DELETE request to delete an existing resource. This method returns true if the delete was successful.

api.lists['abc123'].members['cde345'].delete
# => true

The following errors may be raised by the library, depending on the API response status code.

The exception object has the following methods:

The message should be a simple string given by the API, e.g. "Resource Not Found".

details is a Ruby hash containing all the details given by the server, and looks like this:

{
  "type"     => "http://kb.mailchimp.com/api/error-docs/400-invalid-resource",
  "title"    => "Invalid Resource",
  "status"   => 400,
  "detail"   => "The resource submitted could not be validated. For field-specific details, see the 'errors' array.",
  "instance" => "286179fe-f3dc-4c03-8c14-1021cf0191a2",
  "errors" => [
    {
      "field"   => "",
      "message" => "Required fields were not provided: permission_reminder, campaign_defaults"
    }
  ]
}

Alternatively, you may rescue MailChimp3::Errors::BaseError and branch your code based on the status code returned by calling error.status.

Copyright 2021, Planning Center. Licensed MIT.