Class: MonkeyWrench::List

Inherits:
Base
  • Object
show all
Defined in:
lib/monkey_wrench/list.rb

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

apikey, base_uri, datacenter, default_query_params, default_retry_limit, get, handle_errors, post

Class Method Details

.clear! ⇒ Object

Clears the List cache (results from List.find_all are cached for performance reasons)

Examples:

MonkeyWrench::List.clear!

Returns:

  • nil



65
66
67
 
# File 'lib/monkey_wrench/list.rb', line 65

def self.clear!
  @@lists = nil
end

.find(id) ⇒ MonkeyWrench::List

Finds a given list by ID

Examples:

MonkeyWrench::List.find("0a649eafc3")

Parameters:

  • id (String) —

    the unique Mailchimp list ID

Returns:



38
39
40
 
# File 'lib/monkey_wrench/list.rb', line 38

def self.find(id)
  find_all.find{|e| e.id == id}
end

.find_all ⇒ Array<MonkeyWrench::List> Also known as: all

Finds all lists

Examples:

MonkeyWrench::List.find_all

Returns:



48
49
50
51
52
 
# File 'lib/monkey_wrench/list.rb', line 48

def self.find_all
  @@lists ||= post({ :method => "lists" }).map do |list|
    List.new(list)
  end
end

.find_by_name(list_name) ⇒ MonkeyWrench::List

Finds a given list by name

Examples:

MonkeyWrench::List.find_by_name("My Example List")

Parameters:

  • list_name (String) —

    the list name

Returns:



12
13
14
 
# File 'lib/monkey_wrench/list.rb', line 12

def self.find_by_name(list_name)
  lists = find_all.detect{|list| list.name == list_name}
end

Instance Method Details

#==(other_list) ⇒ Boolean

Will compare another list against the current one and return true if they are the same (based on list ID)

Examples:

list1 = MonkeyWrench::List.find("0a649eafc3")
list2 = MonkeyWrench::List.find("9f9d54a0c4")
list3 = MonkeyWrench::List.find("0a649eafc3") # Same as list1!!
list1 == list2 # false
list1 == list3 # true

Parameters:

Returns:

  • (Boolean) 


27
28
29
 
# File 'lib/monkey_wrench/list.rb', line 27

def ==(other_list)
  other_list.is_a?(self.class) && self.id == other_list.id
end

#each_member(&block) ⇒ Object

Enumerates over each member and executes the provided block. Will automatically page and batch requests for members.

Examples:

list = MonkeyWrench::List.find("0a649eafc3")
emails = []
list.each_member do |member|
  emails << member.email
end

Parameters:

  • &block (Proc) —

    code to execute for each member



110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/monkey_wrench/list.rb', line 110

def each_member(&block)
  page = 0
  loop do
    batch = members(:start => page, :limit => 15000)
    break if batch.empty?
    batch.each do |member|
      yield member
    end
    page += 1
  end
end

#member(email) ⇒ MonkeyWrench::Member

Find a member in this list with the given email address

Examples:

list = MonkeyWrench::List.find("0a649eafc3")
list.member("[email protected]")

Parameters:

  • email (String) —

    members email address

Returns:



163
164
165
166
167
168
169
170
 
# File 'lib/monkey_wrench/list.rb', line 163

def member(email)
  response = post(:id => self.id, :method => "listMemberInfo", :email_address => email)
  if response['error']
    raise response['error']
  else
    MonkeyWrench::Member.new(response)
  end
end

#member?(email) ⇒ Boolean

Check if an email has subscribed to the list

Examples:

list = MonkeyWrench::List.find("0a649eafc3")
list.member?("[email protected]")

Parameters:

  • email (String) —

    members email address

Returns:

  • (Boolean) 


180
181
182
183
184
185
186
187
 
# File 'lib/monkey_wrench/list.rb', line 180

def member?(email)
  response = post(:id => self.id, :method => "listMemberInfo", :email_address => email)
  if response['error']
    false
  else
    true
  end
end

#members(options = {}) ⇒ Array<MonkeyWrench::Member>

Returns all members for this list

Examples:

Find all members that have unsubscribed in the last 24 hours:

MonkeyWrench.members(:status => "unsubscribed",
                     :since => Time.now - 86400)

Parameters:

  • options (Hash) (defaults to: {}) —

    additional option to include when searching.

Options Hash (options):

  • :status (String) — default: 'subscribed' —

    Filter the list members by status. Can be one of the following: “subscribed”, “unsubscribed”, “cleaned”, “updated”.

  • :since (DateTime) —

    Return all members whose status has changed or whose profile has changed since this date/time (in GMT).

  • :start (Integer) — default: 0 —

    For large datasets, the page number to start at.

  • :limit (Integer) — default: 100 —

    For large datasets, the number of results to return. Upper limit is set at 15000.

  • :full_details (Boolean) — default: true —

    Return full member details and not just email address and timestamp.

Returns:



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/monkey_wrench/list.rb', line 82

def members(options = {})
  if options[:since]
    options[:since] = options[:since].strftime("%Y-%m-%d %H:%M:%S")
  end
  options.merge!(:id => self.id, :method => "listMembers")
  response = post(options)
  if options[:full_details]
    response.map do |response_user|
      member(response_user["email"])
    end
  else
    response.map do |response_user|
      MonkeyWrench::Member.new(response_user)
    end
  end
end

#opt_out(emails) ⇒ Hash

Will flag the email(s) as opted-out for all future mailing for this list

Examples:

Opt-out a single user

list = MonkeyWrench::List.find("0a649eafc3")
list.opt_out("[email protected]") # Opt-out a single person

Opt-out a list of users

emails = ["[email protected]", "[email protected]"]
list.opt_out(emails) # Opt-out multiple people at once

Parameters:

  • email (String, Array<String>) —

    address(es) of people to opt-out.

Returns:

  • (Hash) —

    contains 2 keys. :success contains the number of successful actions, :error a list of all errors.



266
267
268
269
270
 
# File 'lib/monkey_wrench/list.rb', line 266

def opt_out(emails)
  emails = [*emails]
  subscribe(emails.map{|email| { :email => email }})
  unsubscribe(emails, :send_goodbye => false, :send_notify => false)
end

#subscribe(contact_details, opts = {}) ⇒ Object

Subscribes a new member to the list

updating an existing member.

Examples:

Subscribe a new email address

list.subscribe("[email protected]")

Subscribe a new member with extended details

list.subscribe({:email => "[email protected]", :type => :html})

Subscribe multiple new members

subscribers = [{:email => "[email protected]", :type => :html},
               {:email => "[email protected]", :type => :html}]
list.subscribe(subscribe, :send_welcome => true, :double_optin => false)

Parameters:

  • contact_details (String, Hash, Array<Hash>) —

    the email address or hash of values for the new member

  • opts (Hash) (defaults to: {}) —

    options when adding new member

Options Hash (opts):

  • :send_welcome (Boolean) — default: false —

    if :double_optin if false and this is true, send the lists ‘Welcome Email’ to the member(s). Will not send email if

  • :double_optin (Boolean) — default: true —

    send an opt-in confirmation email

  • :update_existing (Boolean) — default: false —

    update members that are already subscribed to the list or to return an error (false returns error)

  • :replace_interests (Boolean) — default: true —

    replace interest groups or append to existing interest groups (false appends to groups)



210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/monkey_wrench/list.rb', line 210

def subscribe(contact_details, opts = {})
  if contact_details.is_a?(Array)
    return subscribe_many(contact_details, opts)
  else
    if contact_details.is_a?(Hash)
      email_address = contact_details.delete(:email)
      opts = opts.merge(contact_details)
    else
      email_address = contact_details
    end
    subscribe_one(email_address, opts)
    return { :success => 1, :errors => []}
  end
end

#unsubscribe(emails, opts = {}) ⇒ Hash

Unsubscribes a person (or list of people) from the list

Examples:

Unsubscribe a single user

list = MonkeyWrench::List.find("0a649eafc3")
list.unsubscribe("[email protected]", :send_goodbye => true) # Unsubscribe a single person

Unsubscribe a list of users

emails = ["[email protected]", "[email protected]"]
list.unsubscribe(emails, :send_goodbye => true) # Unsubscribe multiple people at once

Parameters:

  • email (String, Array<String>) —

    address(es) of people to unsubscribe.

  • opts (Hash) (defaults to: {}) —

    additional option to include when unsubscribing.

Options Hash (opts):

  • :delete_member (Boolean) — default: false —

    completely delete the member from your list instead of just unsubscribing.

  • :send_goodbye (Boolean) — default: true —

    send the goodbye email to the email addresses.

  • :send_notify (Boolean) — default: false —

    send the unsubscribe notification email to the address defined in the list email notification settings.

Returns:

  • (Hash) —

    contains 2 keys. :success contains the number of successful actions, :error a list of all errors.



241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/monkey_wrench/list.rb', line 241

def unsubscribe(emails, opts = {})
  emails = [*emails]
  params = { :method => "listBatchUnsubscribe", 
             :id => self.id }
  params[:delete_member] = opts[:delete_member] if opts.has_key?(:delete_member)
  params[:send_goodbye] = opts[:send_goodbye] if opts.has_key?(:send_goodbye)
  params[:send_notify] = opts[:send_notify] if opts.has_key?(:send_notify)
  params.merge!({ :emails => emails }.to_mailchimp)
  response = post(params)
  return { :success => response["success_count"],
           :errors => response["errors"] }
end

#update_members(members, options = {}) ⇒ Object

Updates details of list members

Examples:

Update a single member’s email address

list = MonkeyWrench::List.find("0a649eafc3")
member = {:email => "[email protected]", :new_email => "[email protected]"}
list.update_members(member)

Update multiple members’ email addresses

list = MonkeyWrench::List.find("0a649eafc3")
members = [{:email => "[email protected]", :new_email => "[email protected]"},
           {:email => "[email protected]", :new_email => "[email protected]"}]
list.update_members(members)

Parameters:

  • members (Hash, Array<Hash>) —

    details of member(s) to update details of. Members are matched based on the value of :email, to update the email address assign the new address to :new_email. All other field names are lowercase symbols representing the MERGEVAR name in Mailchimp (e.g., FNAME is :fname)

  • options (Hash) (defaults to: {}) —

    additional options when updating members.

Options Hash (options):

  • :email_type (String) —

    Change the email type preference for the member (‘html’, ‘text’, or ‘mobile’).

  • :replace_interests (Boolean) — default: true —

    replace the interest groups provided (will append interest groups to existing values when false).



143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/monkey_wrench/list.rb', line 143

def update_members(members, options = {})
  members = members.is_a?(Array) ? members : [members]
  options.merge!(:id => self.id, :method => "listUpdateMember")
  members.each do |member|
    mailchimp_args = {:email_address => member[:email]}
    member[:email] = member[:new_email]
    member.delete(:new_email)
    mailchimp_args.merge!({ :merge_vars => member }.to_mailchimp)
    post(options.merge(mailchimp_args))
  end
end