Class: Hominid

Inherits:
Object
  • Object
show all
Defined in:
lib/hominid.rb

Constant Summary collapse

MAILCHIMP_API =

MailChimp API Documentation: www.mailchimp.com/api/1.2/

"http://api.mailchimp.com/1.2/"

Instance Method Summary collapse

Constructor Details

#initialize(config = {}) ⇒ Hominid

Returns a new instance of Hominid.



20
21
22
23
24
25
26
27
28
 
# File 'lib/hominid.rb', line 20

def initialize(config = {})
  if defined?(RAILS_ROOT) && (!config || config.empty?)
    config = YAML.load(File.open("#{RAILS_ROOT}/config/hominid.yml"))[RAILS_ENV].symbolize_keys
  end
  config.merge(:username => config[:username].to_s, :password => config[:password].to_s)
  defaults = {:send_welcome => false, :double_opt_in => false, :update_existing => true, :replace_interests => true, :user_info => {}}
  @config = defaults.merge(config).freeze
  @chimpApi = XMLRPC::Client.new2(MAILCHIMP_API)
end

Instance Method Details

#add_api_key ⇒ Object

Security related methods



32
33
34
 
# File 'lib/hominid.rb', line 32

def add_api_key
  @chimpApi.call("apikeyAdd", *@config.values_at(:username, :password, :api_key))
end

#api_keys(include_expired = false) ⇒ Object 



40
41
42
43
 
# File 'lib/hominid.rb', line 40

def api_keys(include_expired = false)
  username, password = *@config.values_at(:username, :password)
  @chimpApi.call("apikeys", username, password, include_expired)
end

#campaign_content(campaign_id) ⇒ Object

Campaign related methods



47
48
49
50
 
# File 'lib/hominid.rb', line 47

def campaign_content(campaign_id)
  # Get the content of a campaign
  call("campaignContent", campaign_id)
end

#campaign_ecomm_add_order(order) ⇒ Object

Attach Ecommerce Order Information to a Campaign. The order hash should be structured as follows:

:id             = (string)  the order id 
:campaign_id    = (string)  the campaign id to track the order (mc_cid query string). 
:email_id       = (string)  email id of the subscriber (mc_eid query string)
:total          = (double)  Show only campaigns with this from_name.
:shipping       = (string)  *optional - the total paid for shipping fees.
:tax            = (string)  *optional - the total tax paid.
:store_id       = (string)  a unique id for the store sending the order in
:store_name     = (string)  *optional - A readable name for the store, typicaly the hostname.
:plugin_id      = (string)  the MailChimp-assigned Plugin Id. Using 1214 for the moment. 
:items          = (array)   the individual line items for an order, using the following keys:

  :line_num      = (integer) *optional - line number of the item on the order
  :product_id    = (integer) internal product id
  :product_name  = (string)  the name for the product_id associated with the item
  :category_id   = (integer) internal id for the (main) category associated with product
  :category_name = (string)  the category name for the category id
  :qty           = (double)  the quantity of items ordered
  :cost          = (double)  the cost of a single item (i.e., not the extended cost of the line)



91
92
93
 
# File 'lib/hominid.rb', line 91

def campaign_ecomm_add_order(order)
  call("campaignEcommAddOrder", order)
end

#campaigns(filters = {}, start = 0, limit = 50) ⇒ Object 



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/hominid.rb', line 52

def campaigns(filters = {}, start = 0, limit = 50)
  # Get the campaigns for this account
  # API Version 1.2 requires that filters be sent as a hash
  # Available options for the filters hash are:
  #
  #   :campaign_id    = (string)  The ID of the campaign you wish to return. 
  #   :list_id        = (string)  Show only campaigns with this list_id. 
  #   :folder_id      = (integer) Show only campaigns from this folder.
  #   :from_name      = (string)  Show only campaigns with this from_name.
  #   :from_email     = (string)  Show only campaigns with this from_email.
  #   :title          = (string)  Show only campaigns with this title.
  #   :subject        = (string)  Show only campaigns with this subject.
  #   :sedtime_start  = (string)  Show campaigns sent after YYYY-MM-DD HH:mm:ss.
  #   :sendtime_end   = (string)  Show campaigns sent before YYYY-MM-DD HH:mm:ss.
  #   :subject        = (boolean) Filter by exact values, or search within content for filter values.
  call("campaigns", filters, start, limit)
end

#convert_css_to_inline(html, strip_css = false) ⇒ Object 



148
149
150
151
 
# File 'lib/hominid.rb', line 148

def convert_css_to_inline(html, strip_css = false)
  # Convert CSS styles to inline styles and (optionally) remove original styles
  call("inlineCss", html, strip_css)
end

#create_campaign(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {}) ⇒ Object 



95
96
97
98
 
# File 'lib/hominid.rb', line 95

def create_campaign(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {})
  # Create a new campaign
  call("campaignCreate", type, options, content, segment_options, type_opts)
end

#create_group(list_id, group) ⇒ Object 



160
161
162
163
 
# File 'lib/hominid.rb', line 160

def create_group(list_id, group)
  # Add an interest group to a list
  call("listInterestGroupAdd", list_id, group)
end

#create_tag(list_id, tag, name, required = false) ⇒ Object 



165
166
167
168
 
# File 'lib/hominid.rb', line 165

def create_tag(list_id, tag, name, required = false)
  # Add a merge tag to a list
  call("listMergeVarAdd", list_id, tag, name, required)
end

#delete_campaign(campaign_id) ⇒ Object 



100
101
102
103
 
# File 'lib/hominid.rb', line 100

def delete_campaign(campaign_id)
  # Delete a campaign
  call("campaignDelete", campaign_id)
end

#delete_group(list_id, group) ⇒ Object 



170
171
172
173
 
# File 'lib/hominid.rb', line 170

def delete_group(list_id, group)
  # Delete an interest group for a list
  call("listInterestGroupDel", list_id, group)
end

#delete_tag(list_id, tag) ⇒ Object 



175
176
177
178
 
# File 'lib/hominid.rb', line 175

def delete_tag(list_id, tag)
  # Delete a merge tag and all its members
  call("listMergeVarDel", list_id, tag)
end

#expire_api_key ⇒ Object 



36
37
38
 
# File 'lib/hominid.rb', line 36

def expire_api_key
  @chimpApi.call("apikeyExpire", *@config.values_at(:username, :password, :api_key))
end

#groups(list_id) ⇒ Object 



180
181
182
183
 
# File 'lib/hominid.rb', line 180

def groups(list_id)
  # Get the interest groups for a list
  call("listInterestGroups", list_id)
end

#html_to_text(content) ⇒ Object

Helper methods



143
144
145
146
 
# File 'lib/hominid.rb', line 143

def html_to_text(content)
  # Convert HTML content to text
  call("generateText", 'html', content)
end

#lists ⇒ Object

List related methods



155
156
157
158
 
# File 'lib/hominid.rb', line 155

def lists
  # Get all of the lists for this mailchimp account
  call("lists")
end

#member(list_id, email) ⇒ Object 



185
186
187
188
 
# File 'lib/hominid.rb', line 185

def member(list_id, email)
  # Get a member of a list
  call("listMemberInfo", list_id, email)
end

#members(list_id, status = "subscribed", since = "2000-01-01 00:00:00", start = 0, limit = 100) ⇒ Object 



190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/hominid.rb', line 190

def members(list_id, status = "subscribed", since = "2000-01-01 00:00:00", start = 0, limit = 100)
  # Get members of a list based on status
  # Select members based on one of the following statuses:
  #   'subscribed'
  #   'unsubscribed'
  #   'cleaned'
  #   'updated'
  #
  # Select members that have updated their status or profile by providing
  # a "since" date in the format of YYYY-MM-DD HH:MM:SS
  # 
  call("listMembers", list_id, status, since, start, limit)
end

#merge_tags(list_id) ⇒ Object 



204
205
206
207
 
# File 'lib/hominid.rb', line 204

def merge_tags(list_id)
  # Get the merge tags for a list
  call("listMergeVars", list_id)
end

#replicate_campaign(campaign_id) ⇒ Object 



105
106
107
108
 
# File 'lib/hominid.rb', line 105

def replicate_campaign(campaign_id)
  # Replicate a campaign (returns ID of new campaign)
  call("campaignReplicate", campaign_id)
end

#schedule_campaign(campaign_id, time = "#{1.day.from_now}") ⇒ Object 



110
111
112
113
114
 
# File 'lib/hominid.rb', line 110

def schedule_campaign(campaign_id, time = "#{1.day.from_now}")
  # Schedule a campaign
  ## TODO: Add support for A/B Split scheduling
  call("campaignSchedule", campaign_id, time)
end

#send_now(campaign_id) ⇒ Object 



116
117
118
119
 
# File 'lib/hominid.rb', line 116

def send_now(campaign_id)
  # Send a campaign
  call("campaignSendNow", campaign_id)
end

#send_test(campaign_id, emails = {}) ⇒ Object 



121
122
123
124
 
# File 'lib/hominid.rb', line 121

def send_test(campaign_id, emails = {})
  # Send a test of a campaign
  call("campaignSendTest", campaign_id, emails)
end

#subscribe(list_id, email, options = {}) ⇒ Object 



209
210
211
212
213
 
# File 'lib/hominid.rb', line 209

def subscribe(list_id, email, options = {})
  options = apply_defaults_to({:email_type => "html"}.merge(options))
  # Subscribe a member
  call("listSubscribe", list_id, email, *options.values_at(:user_info, :email_type, :double_opt_in, :update_existing, :replace_interests, :send_welcome))
end

#subscribe_many(list_id, subscribers, options = {}) ⇒ Object 



215
216
217
218
219
220
 
# File 'lib/hominid.rb', line 215

def subscribe_many(list_id, subscribers, options = {})
  options = apply_defaults_to({:update_existing => true}.merge(options))
  # Subscribe a batch of members
  # subscribers = {:EMAIL => '[email protected]', :EMAIL_TYPE => 'html'} 
  call("listBatchSubscribe", list_id, subscribers, *options.values_at(:double_opt_in, :update_existing, :replace_interests))
end

#templates ⇒ Object 



126
127
128
129
 
# File 'lib/hominid.rb', line 126

def templates
  # Get the templates
  call("campaignTemplates")
end

#unschedule_campaign(campaign_id) ⇒ Object 



136
137
138
139
 
# File 'lib/hominid.rb', line 136

def unschedule_campaign(campaign_id)
  # Unschedule a campaign
  call("campaignUnschedule", campaign_id)
end

#unsubscribe(list_id, current_email, options = {}) ⇒ Object 



222
223
224
225
226
 
# File 'lib/hominid.rb', line 222

def unsubscribe(list_id, current_email, options = {})
  options = apply_defaults_to({:delete_member => true}.merge(options))
  # Unsubscribe a list member
  call("listUnsubscribe", list_id, current_email, *options.values_at(:delete_member, :send_goodbye, :send_notify))
end

#unsubscribe_many(list_id, emails, options = {}) ⇒ Object 



228
229
230
231
232
233
 
# File 'lib/hominid.rb', line 228

def unsubscribe_many(list_id, emails, options = {})
  options = apply_defaults_to({:delete_member => true}.merge(options))
  # Unsubscribe an array of email addresses
  # emails = ['[email protected]', '[email protected]'] 
  call("listBatchUnsubscribe", list_id, emails, *options.values_at(:delete_member, :send_goodbye, :send_notify))
end

#update_campaign(campaign_id, name, value) ⇒ Object 



131
132
133
134
 
# File 'lib/hominid.rb', line 131

def update_campaign(campaign_id, name, value)
  # Update a campaign
  call("campaignUpdate", campaign_id, name, value)
end

#update_member(list_id, current_email, user_info = {}, email_type = "") ⇒ Object 



235
236
237
238
 
# File 'lib/hominid.rb', line 235

def update_member(list_id, current_email,  = {}, email_type = "")
  # Update a member of this list
  call("listUpdateMember", list_id, current_email, , email_type, true)
end