Class: Mailchimp::Lists

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(master) ⇒ Lists 



554
555
556
 
# File 'lib/mailchimp/api.rb', line 554

def initialize(master)
    @master = master
end

Instance Attribute Details

#master ⇒ Object

Returns the value of attribute master.



552
553
554
 
# File 'lib/mailchimp/api.rb', line 552

def master
  @master
end

Instance Method Details

#abuse_reports(id, start = 0, limit = 500, since = nil) ⇒ Hash

Get all email addresses that complained about a campaign sent to a list



570
571
572
573
 
# File 'lib/mailchimp/api.rb', line 570

def abuse_reports(id, start=0, limit=500, since=nil)
    _params = {:id => id, :start => start, :limit => limit, :since => since}
    return @master.call 'lists/abuse-reports', _params
end

#activity(id) ⇒ Array

Access up to the previous 180 days of daily detailed aggregated activity stats for a given list. Does not include AutoResponder activity.



578
579
580
581
 
# File 'lib/mailchimp/api.rb', line 578

def activity(id)
    _params = {:id => id}
    return @master.call 'lists/activity', _params
end

#batch_subscribe(id, batch, double_optin = true, update_existing = false, replace_interests = true) ⇒ Hash

Subscribe a batch of email addresses to a list at once. If you are using a serialized version of the API, we strongly suggest that you only run this method as a POST request, and not a GET request. Maximum batch sizes vary based on the amount of data in each record, though you should cap them at 5k - 10k records, depending on your experience. These calls are also long, so be sure you increase your timeout values.



615
616
617
618
 
# File 'lib/mailchimp/api.rb', line 615

def batch_subscribe(id, batch, double_optin=true, update_existing=false, replace_interests=true)
    _params = {:id => id, :batch => batch, :double_optin => double_optin, :update_existing => update_existing, :replace_interests => replace_interests}
    return @master.call 'lists/batch-subscribe', _params
end

#batch_unsubscribe(id, batch, delete_member = false, send_goodbye = true, send_notify = false) ⇒ Array

Unsubscribe a batch of email addresses from a list



640
641
642
643
 
# File 'lib/mailchimp/api.rb', line 640

def batch_unsubscribe(id, batch, delete_member=false, send_goodbye=true, send_notify=false)
    _params = {:id => id, :batch => batch, :delete_member => delete_member, :send_goodbye => send_goodbye, :send_notify => send_notify}
    return @master.call 'lists/batch-unsubscribe', _params
end

#clients(id) ⇒ Hash

Retrieve the clients that the list’s subscribers have been tagged as being used based on user agents seen. Made possible by <a href=“user-agent-string.info” target=“_blank”>user-agent-string.info</a>



662
663
664
665
 
# File 'lib/mailchimp/api.rb', line 662

def clients(id)
    _params = {:id => id}
    return @master.call 'lists/clients', _params
end

#growth_history(id = nil) ⇒ Array

Access the Growth History by Month in aggregate or for a given list.



674
675
676
677
 
# File 'lib/mailchimp/api.rb', line 674

def growth_history(id=nil)
    _params = {:id => id}
    return @master.call 'lists/growth-history', _params
end

#interest_group_add(id, group_name, grouping_id = nil) ⇒ Hash

Add a single Interest Group - if interest groups for the List are not yet enabled, adding the first group will automatically turn them on.



702
703
704
705
 
# File 'lib/mailchimp/api.rb', line 702

def interest_group_add(id, group_name, grouping_id=nil)
    _params = {:id => id, :group_name => group_name, :grouping_id => grouping_id}
    return @master.call 'lists/interest-group-add', _params
end

#interest_group_del(id, group_name, grouping_id = nil) ⇒ Hash

Delete a single Interest Group - if the last group for a list is deleted, this will also turn groups for the list off.



713
714
715
716
 
# File 'lib/mailchimp/api.rb', line 713

def interest_group_del(id, group_name, grouping_id=nil)
    _params = {:id => id, :group_name => group_name, :grouping_id => grouping_id}
    return @master.call 'lists/interest-group-del', _params
end

#interest_group_update(id, old_name, new_name, grouping_id = nil) ⇒ Hash

Change the name of an Interest Group



725
726
727
728
 
# File 'lib/mailchimp/api.rb', line 725

def interest_group_update(id, old_name, new_name, grouping_id=nil)
    _params = {:id => id, :old_name => old_name, :new_name => new_name, :grouping_id => grouping_id}
    return @master.call 'lists/interest-group-update', _params
end

#interest_grouping_add(id, name, type, groups) ⇒ Hash

Add a new Interest Grouping - if interest groups for the List are not yet enabled, adding the first grouping will automatically turn them on.



737
738
739
740
 
# File 'lib/mailchimp/api.rb', line 737

def interest_grouping_add(id, name, type, groups)
    _params = {:id => id, :name => name, :type => type, :groups => groups}
    return @master.call 'lists/interest-grouping-add', _params
end

#interest_grouping_del(grouping_id) ⇒ Hash

Delete an existing Interest Grouping - this will permanently delete all contained interest groups and will remove those selections from all list members



746
747
748
749
 
# File 'lib/mailchimp/api.rb', line 746

def interest_grouping_del(grouping_id)
    _params = {:grouping_id => grouping_id}
    return @master.call 'lists/interest-grouping-del', _params
end

#interest_grouping_update(grouping_id, name, value) ⇒ Hash

Update an existing Interest Grouping



757
758
759
760
 
# File 'lib/mailchimp/api.rb', line 757

def interest_grouping_update(grouping_id, name, value)
    _params = {:grouping_id => grouping_id, :name => name, :value => value}
    return @master.call 'lists/interest-grouping-update', _params
end

#interest_groupings(id, counts = false) ⇒ Array

Get the list of interest groupings for a given list, including the label, form information, and included groups for each



691
692
693
694
 
# File 'lib/mailchimp/api.rb', line 691

def interest_groupings(id, counts=false)
    _params = {:id => id, :counts => counts}
    return @master.call 'lists/interest-groupings', _params
end

#list(filters = [], start = 0, limit = 25, sort_field = 'created', sort_dir = 'DESC') ⇒ Hash

Retrieve all of the lists defined for your user account



1338
1339
1340
1341
 
# File 'lib/mailchimp/api.rb', line 1338

def list(filters=[], start=0, limit=25, sort_field='created', sort_dir='DESC')
    _params = {:filters => filters, :start => start, :limit => limit, :sort_field => sort_field, :sort_dir => sort_dir}
    return @master.call 'lists/list', _params
end

#locations(id) ⇒ Array

Retrieve the locations (countries) that the list’s subscribers have been tagged to based on geocoding their IP address



769
770
771
772
 
# File 'lib/mailchimp/api.rb', line 769

def locations(id)
    _params = {:id => id}
    return @master.call 'lists/locations', _params
end

#member_activity(id, emails) ⇒ Hash

Get the most recent 100 activities for particular list members (open, click, bounce, unsub, abuse, sent to, etc.)



802
803
804
805
 
# File 'lib/mailchimp/api.rb', line 802

def member_activity(id, emails)
    _params = {:id => id, :emails => emails}
    return @master.call 'lists/member-activity', _params
end

#member_info(id, emails) ⇒ Hash

Get all the information for particular members of a list



872
873
874
875
 
# File 'lib/mailchimp/api.rb', line 872

def member_info(id, emails)
    _params = {:id => id, :emails => emails}
    return @master.call 'lists/member-info', _params
end

#members(id, status = 'subscribed', opts = []) ⇒ Hash

Get all of the list members for a list that are of a particular status and potentially matching a segment. This will cause locking, so don’t run multiples at once. Are you trying to get a dump including lots of merge data or specific members of a list? If so, checkout the <a href=“/export/1.0/list.func.php”>List Export API</a>



889
890
891
892
 
# File 'lib/mailchimp/api.rb', line 889

def members(id, status='subscribed', opts=[])
    _params = {:id => id, :status => status, :opts => opts}
    return @master.call 'lists/members', _params
end

#merge_var_add(id, tag, name, options = []) ⇒ Hash

Add a new merge tag to a given list



923
924
925
926
 
# File 'lib/mailchimp/api.rb', line 923

def merge_var_add(id, tag, name, options=[])
    _params = {:id => id, :tag => tag, :name => name, :options => options}
    return @master.call 'lists/merge-var-add', _params
end

#merge_var_del(id, tag) ⇒ Hash

Delete a merge tag from a given list and all its members. Seriously - the data is removed from all members as well! Note that on large lists this method may seem a bit slower than calls you typically make.



933
934
935
936
 
# File 'lib/mailchimp/api.rb', line 933

def merge_var_del(id, tag)
    _params = {:id => id, :tag => tag}
    return @master.call 'lists/merge-var-del', _params
end

#merge_var_reset(id, tag) ⇒ Hash

Completely resets all data stored in a merge var on a list. All data is removed and this action can not be undone.



943
944
945
946
 
# File 'lib/mailchimp/api.rb', line 943

def merge_var_reset(id, tag)
    _params = {:id => id, :tag => tag}
    return @master.call 'lists/merge-var-reset', _params
end

#merge_var_set(id, tag, value) ⇒ Hash

Sets a particular merge var to the specified value for every list member. Only merge var ids 1 - 30 may be modified this way. This is generally a dirty method unless you’re fixing data since you should probably be using default_values and/or conditional content. as with lists/merge-var-reset(), this can not be undone.



954
955
956
957
 
# File 'lib/mailchimp/api.rb', line 954

def merge_var_set(id, tag, value)
    _params = {:id => id, :tag => tag, :value => value}
    return @master.call 'lists/merge-var-set', _params
end

#merge_var_update(id, tag, options) ⇒ Hash

Update most parameters for a merge tag on a given list. You cannot currently change the merge type



976
977
978
979
 
# File 'lib/mailchimp/api.rb', line 976

def merge_var_update(id, tag, options)
    _params = {:id => id, :tag => tag, :options => options}
    return @master.call 'lists/merge-var-update', _params
end

#merge_vars(id) ⇒ Hash

Get the list of merge tags for a given list, including their name, tag, and required setting



1006
1007
1008
1009
 
# File 'lib/mailchimp/api.rb', line 1006

def merge_vars(id)
    _params = {:id => id}
    return @master.call 'lists/merge-vars', _params
end

#segment_add(id, opts) ⇒ Hash

Save a segment against a list for later use. There is no limit to the number of segments which can be saved. Static Segments <strong>are not</strong> tied to any merge data, interest groups, etc. They essentially allow you to configure an unlimited number of custom segments which will have standard performance. When using proper segments, Static Segments are one of the available options for segmentation just as if you used a merge var (and they can be used with other segmentation options), though performance may degrade at that point. Saved Segments (called “auto-updating” in the app) are essentially just the match+conditions typically used.



1033
1034
1035
1036
 
# File 'lib/mailchimp/api.rb', line 1033

def segment_add(id, opts)
    _params = {:id => id, :opts => opts}
    return @master.call 'lists/segment-add', _params
end

#segment_del(id, seg_id) ⇒ Hash

Delete a segment. Note that this will, of course, remove any member affiliations with any static segments deleted



1043
1044
1045
1046
 
# File 'lib/mailchimp/api.rb', line 1043

def segment_del(id, seg_id)
    _params = {:id => id, :seg_id => seg_id}
    return @master.call 'lists/segment-del', _params
end

#segment_test(list_id, options) ⇒ Hash

Allows one to test their segmentation rules before creating a campaign using them - this is no different from campaigns/segment-test() and will eventually replace it. For the time being, the crazy segmenting condition documentation will continue to live over there.



1056
1057
1058
1059
 
# File 'lib/mailchimp/api.rb', line 1056

def segment_test(list_id, options)
    _params = {:list_id => list_id, :options => options}
    return @master.call 'lists/segment-test', _params
end

#segment_update(id, seg_id, opts) ⇒ Hash

Update an existing segment. The list and type can not be changed.



1071
1072
1073
1074
 
# File 'lib/mailchimp/api.rb', line 1071

def segment_update(id, seg_id, opts)
    _params = {:id => id, :seg_id => seg_id, :opts => opts}
    return @master.call 'lists/segment-update', _params
end

#segments(id, type = nil) ⇒ Hash

Retrieve all of Segments for a list.



1018
1019
1020
1021
 
# File 'lib/mailchimp/api.rb', line 1018

def segments(id, type=nil)
    _params = {:id => id, :type => type}
    return @master.call 'lists/segments', _params
end

#static_segment_add(id, name) ⇒ Hash

Save a segment against a list for later use. There is no limit to the number of segments which can be saved. Static Segments <strong>are not</strong> tied to any merge data, interest groups, etc. They essentially allow you to configure an unlimited number of custom segments which will have standard performance. When using proper segments, Static Segments are one of the available options for segmentation just as if you used a merge var (and they can be used with other segmentation options), though performance may degrade at that point.



1081
1082
1083
1084
 
# File 'lib/mailchimp/api.rb', line 1081

def static_segment_add(id, name)
    _params = {:id => id, :name => name}
    return @master.call 'lists/static-segment-add', _params
end

#static_segment_del(id, seg_id) ⇒ Hash

Delete a static segment. Note that this will, of course, remove any member affiliations with the segment



1091
1092
1093
1094
 
# File 'lib/mailchimp/api.rb', line 1091

def static_segment_del(id, seg_id)
    _params = {:id => id, :seg_id => seg_id}
    return @master.call 'lists/static-segment-del', _params
end

#static_segment_members_add(id, seg_id, batch) ⇒ Hash

Add list members to a static segment. It is suggested that you limit batch size to no more than 10,000 addresses per call. Email addresses must exist on the list in order to be included - this <strong>will not</strong> subscribe them to the list!



1112
1113
1114
1115
 
# File 'lib/mailchimp/api.rb', line 1112

def static_segment_members_add(id, seg_id, batch)
    _params = {:id => id, :seg_id => seg_id, :batch => batch}
    return @master.call 'lists/static-segment-members-add', _params
end

#static_segment_members_del(id, seg_id, batch) ⇒ Hash

Remove list members from a static segment. It is suggested that you limit batch size to no more than 10,000 addresses per call. Email addresses must exist on the list in order to be removed - this <strong>will not</strong> unsubscribe them from the list!



1134
1135
1136
1137
 
# File 'lib/mailchimp/api.rb', line 1134

def static_segment_members_del(id, seg_id, batch)
    _params = {:id => id, :seg_id => seg_id, :batch => batch}
    return @master.call 'lists/static-segment-members-del', _params
end

#static_segment_reset(id, seg_id) ⇒ Hash

Resets a static segment - removes <strong>all</strong> members from the static segment. Note: does not actually affect list member data



1144
1145
1146
1147
 
# File 'lib/mailchimp/api.rb', line 1144

def static_segment_reset(id, seg_id)
    _params = {:id => id, :seg_id => seg_id}
    return @master.call 'lists/static-segment-reset', _params
end

#static_segments(id) ⇒ Array

Retrieve all of the Static Segments for a list.



1158
1159
1160
1161
 
# File 'lib/mailchimp/api.rb', line 1158

def static_segments(id)
    _params = {:id => id}
    return @master.call 'lists/static-segments', _params
end

#subscribe(id, email, merge_vars = nil, email_type = 'html', double_optin = true, update_existing = false, replace_interests = true, send_welcome = false) ⇒ Hash

Subscribe the provided email to a list. By default this sends a confirmation email - you will not see new members until the link contained in it is clicked!



1195
1196
1197
1198
 
# File 'lib/mailchimp/api.rb', line 1195

def subscribe(id, email, merge_vars=nil, email_type='html', double_optin=true, update_existing=false, replace_interests=true, send_welcome=false)
    _params = {:id => id, :email => email, :merge_vars => merge_vars, :email_type => email_type, :double_optin => double_optin, :update_existing => update_existing, :replace_interests => replace_interests, :send_welcome => send_welcome}
    return @master.call 'lists/subscribe', _params
end

#unsubscribe(id, email, delete_member = false, send_goodbye = true, send_notify = true) ⇒ Hash

Unsubscribe the given email address from the list



1211
1212
1213
1214
 
# File 'lib/mailchimp/api.rb', line 1211

def unsubscribe(id, email, delete_member=false, send_goodbye=true, send_notify=true)
    _params = {:id => id, :email => email, :delete_member => delete_member, :send_goodbye => send_goodbye, :send_notify => send_notify}
    return @master.call 'lists/unsubscribe', _params
end

#update_member(id, email, merge_vars, email_type = '', replace_interests = true) ⇒ Hash

Edit the email address, merge fields, and interest groups for a list member. If you are doing a batch update on lots of users, consider using lists/batch-subscribe() with the update_existing and possible replace_interests parameter.



1229
1230
1231
1232
 
# File 'lib/mailchimp/api.rb', line 1229

def update_member(id, email, merge_vars, email_type='', replace_interests=true)
    _params = {:id => id, :email => email, :merge_vars => merge_vars, :email_type => email_type, :replace_interests => replace_interests}
    return @master.call 'lists/update-member', _params
end

#webhook_add(id, url, actions = [], sources = []) ⇒ Hash

Add a new Webhook URL for the given list



1250
1251
1252
1253
 
# File 'lib/mailchimp/api.rb', line 1250

def webhook_add(id, url, actions=[], sources=[])
    _params = {:id => id, :url => url, :actions => actions, :sources => sources}
    return @master.call 'lists/webhook-add', _params
end

#webhook_del(id, url) ⇒ Hash

Delete an existing Webhook URL from a given list



1260
1261
1262
1263
 
# File 'lib/mailchimp/api.rb', line 1260

def webhook_del(id, url)
    _params = {:id => id, :url => url}
    return @master.call 'lists/webhook-del', _params
end

#webhooks(id) ⇒ Array

Return the Webhooks configured for the given list



1280
1281
1282
1283
 
# File 'lib/mailchimp/api.rb', line 1280

def webhooks(id)
    _params = {:id => id}
    return @master.call 'lists/webhooks', _params
end