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_options, get, handle_errors, post

Class Method Details

.find(id) ⇒ MonkeyWrench::List

Finds a given list by ID

Examples:

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

Parameters:

  • id (String) —

    the unique Mailchimp list ID

Returns:



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

def self.find(id)
  new(:id => id)
end

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

Finds all lists

Examples:

MonkeyWrench::List.find_all

Returns:



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

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:



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

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) 


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

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



99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/monkey_wrench/list.rb', line 99

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:



152
153
154
155
156
157
158
159
 
# File 'lib/monkey_wrench/list.rb', line 152

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

#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:



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/monkey_wrench/list.rb', line 71

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.



238
239
240
241
242
 
# File 'lib/monkey_wrench/list.rb', line 238

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)



182
183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/monkey_wrench/list.rb', line 182

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.



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

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).



132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/monkey_wrench/list.rb', line 132

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