Class: Mailchimp::Lists
- Inherits:
-
Object
- Object
- Mailchimp::Lists
- Defined in:
- lib/mailchimp/api.rb
Instance Attribute Summary collapse
-
#master ⇒ Object
Returns the value of attribute master.
Instance Method Summary collapse
-
#abuse_reports(id, start = 0, limit = 500, since = nil) ⇒ Hash
Get all email addresses that complained about a campaign sent to a list.
-
#activity(id) ⇒ Array
Access up to the previous 180 days of daily detailed aggregated activity stats for a given list.
-
#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.
-
#batch_unsubscribe(id, batch, delete_member = false, send_goodbye = true, send_notify = false) ⇒ Array
Unsubscribe a batch of email addresses from a list.
-
#clients(id) ⇒ Hash
Retrieve the clients that the list’s subscribers have been tagged as being used based on user agents seen.
-
#growth_history(id = nil) ⇒ Array
Access the Growth History by Month in aggregate or for a given list.
-
#initialize(master) ⇒ Lists
constructor
A new instance of Lists.
-
#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.
-
#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.
-
#interest_group_update(id, old_name, new_name, grouping_id = nil) ⇒ Hash
Change the name of an Interest Group.
-
#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.
-
#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.
-
#interest_grouping_update(grouping_id, name, value) ⇒ Hash
Update an existing Interest Grouping.
-
#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.
-
#list(filters = [], start = 0, limit = 25, sort_field = 'created', sort_dir = 'DESC') ⇒ Hash
Retrieve all of the lists defined for your user account.
-
#locations(id) ⇒ Array
Retrieve the locations (countries) that the list’s subscribers have been tagged to based on geocoding their IP address.
-
#member_activity(id, emails) ⇒ Hash
Get the most recent 100 activities for particular list members (open, click, bounce, unsub, abuse, sent to, etc.).
-
#member_info(id, emails) ⇒ Hash
Get all the information for particular members of a list.
-
#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.
-
#merge_var_add(id, tag, name, options = []) ⇒ Hash
Add a new merge tag to a given list.
-
#merge_var_del(id, tag) ⇒ Hash
Delete a merge tag from a given list and all its members.
-
#merge_var_reset(id, tag) ⇒ Hash
Completely resets all data stored in a merge var on a list.
-
#merge_var_set(id, tag, value) ⇒ Hash
Sets a particular merge var to the specified value for every list member.
-
#merge_var_update(id, tag, options) ⇒ Hash
Update most parameters for a merge tag on a given list.
-
#merge_vars(id) ⇒ Hash
Get the list of merge tags for a given list, including their name, tag, and required setting.
-
#segment_add(id, opts) ⇒ Hash
Save a segment against a list for later use.
-
#segment_del(id, seg_id) ⇒ Hash
Delete a segment.
-
#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.
-
#segment_update(id, seg_id, opts) ⇒ Hash
Update an existing segment.
-
#segments(id, type = nil) ⇒ Hash
Retrieve all of Segments for a list.
-
#static_segment_add(id, name) ⇒ Hash
Save a segment against a list for later use.
-
#static_segment_del(id, seg_id) ⇒ Hash
Delete a static segment.
-
#static_segment_members_add(id, seg_id, batch) ⇒ Hash
Add list members to a static segment.
-
#static_segment_members_del(id, seg_id, batch) ⇒ Hash
Remove list members from a static segment.
-
#static_segment_reset(id, seg_id) ⇒ Hash
Resets a static segment - removes <strong>all</strong> members from the static segment.
-
#static_segments(id, get_counts = true, start = 0, limit = nil) ⇒ Array
Retrieve all of the Static Segments for a list.
-
#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.
-
#unsubscribe(id, email, delete_member = false, send_goodbye = true, send_notify = true) ⇒ Hash
Unsubscribe the given email address from the list.
-
#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.
-
#webhook_add(id, url, actions = [], sources = []) ⇒ Hash
Add a new Webhook URL for the given list.
-
#webhook_del(id, url) ⇒ Hash
Delete an existing Webhook URL from a given list.
-
#webhooks(id) ⇒ Array
Return the Webhooks configured for the given list.
Constructor Details
#initialize(master) ⇒ Lists
Returns a new instance of Lists.
623 624 625 |
# File 'lib/mailchimp/api.rb', line 623 def initialize(master) @master = master end |
Instance Attribute Details
#master ⇒ Object
Returns the value of attribute master.
621 622 623 |
# File 'lib/mailchimp/api.rb', line 621 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
639 640 641 642 |
# File 'lib/mailchimp/api.rb', line 639 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.
647 648 649 650 |
# File 'lib/mailchimp/api.rb', line 647 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.
684 685 686 687 |
# File 'lib/mailchimp/api.rb', line 684 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
708 709 710 711 |
# File 'lib/mailchimp/api.rb', line 708 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>
730 731 732 733 |
# File 'lib/mailchimp/api.rb', line 730 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.
742 743 744 745 |
# File 'lib/mailchimp/api.rb', line 742 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.
770 771 772 773 |
# File 'lib/mailchimp/api.rb', line 770 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.
781 782 783 784 |
# File 'lib/mailchimp/api.rb', line 781 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
793 794 795 796 |
# File 'lib/mailchimp/api.rb', line 793 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.
805 806 807 808 |
# File 'lib/mailchimp/api.rb', line 805 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
814 815 816 817 |
# File 'lib/mailchimp/api.rb', line 814 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
825 826 827 828 |
# File 'lib/mailchimp/api.rb', line 825 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
759 760 761 762 |
# File 'lib/mailchimp/api.rb', line 759 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
1416 1417 1418 1419 |
# File 'lib/mailchimp/api.rb', line 1416 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
837 838 839 840 |
# File 'lib/mailchimp/api.rb', line 837 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.)
870 871 872 873 |
# File 'lib/mailchimp/api.rb', line 870 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
940 941 942 943 |
# File 'lib/mailchimp/api.rb', line 940 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>
957 958 959 960 |
# File 'lib/mailchimp/api.rb', line 957 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
991 992 993 994 |
# File 'lib/mailchimp/api.rb', line 991 def merge_var_add(id, tag, name, =[]) _params = {:id => id, :tag => tag, :name => name, :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.
1001 1002 1003 1004 |
# File 'lib/mailchimp/api.rb', line 1001 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.
1011 1012 1013 1014 |
# File 'lib/mailchimp/api.rb', line 1011 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.
1022 1023 1024 1025 |
# File 'lib/mailchimp/api.rb', line 1022 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
1044 1045 1046 1047 |
# File 'lib/mailchimp/api.rb', line 1044 def merge_var_update(id, tag, ) _params = {:id => id, :tag => tag, :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
1074 1075 1076 1077 |
# File 'lib/mailchimp/api.rb', line 1074 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.
1111 1112 1113 1114 |
# File 'lib/mailchimp/api.rb', line 1111 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
1121 1122 1123 1124 |
# File 'lib/mailchimp/api.rb', line 1121 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.
1131 1132 1133 1134 |
# File 'lib/mailchimp/api.rb', line 1131 def segment_test(list_id, ) _params = {:list_id => list_id, :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.
1146 1147 1148 1149 |
# File 'lib/mailchimp/api.rb', line 1146 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.
1096 1097 1098 1099 |
# File 'lib/mailchimp/api.rb', line 1096 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.
1156 1157 1158 1159 |
# File 'lib/mailchimp/api.rb', line 1156 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
1166 1167 1168 1169 |
# File 'lib/mailchimp/api.rb', line 1166 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!
1187 1188 1189 1190 |
# File 'lib/mailchimp/api.rb', line 1187 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!
1209 1210 1211 1212 |
# File 'lib/mailchimp/api.rb', line 1209 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
1219 1220 1221 1222 |
# File 'lib/mailchimp/api.rb', line 1219 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, get_counts = true, start = 0, limit = nil) ⇒ Array
Retrieve all of the Static Segments for a list.
1236 1237 1238 1239 |
# File 'lib/mailchimp/api.rb', line 1236 def static_segments(id, get_counts=true, start=0, limit=nil) _params = {:id => id, :get_counts => get_counts, :start => start, :limit => limit} 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!
1273 1274 1275 1276 |
# File 'lib/mailchimp/api.rb', line 1273 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
1289 1290 1291 1292 |
# File 'lib/mailchimp/api.rb', line 1289 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.
1307 1308 1309 1310 |
# File 'lib/mailchimp/api.rb', line 1307 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
1328 1329 1330 1331 |
# File 'lib/mailchimp/api.rb', line 1328 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
1338 1339 1340 1341 |
# File 'lib/mailchimp/api.rb', line 1338 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
1358 1359 1360 1361 |
# File 'lib/mailchimp/api.rb', line 1358 def webhooks(id) _params = {:id => id} return @master.call 'lists/webhooks', _params end |