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

Returns a new instance of Lists.



541
542
543
 
# File 'lib/mailchimp/api.rb', line 541

def initialize(master)
    @master = master
end

Instance Attribute Details

#master ⇒ Object

Returns the value of attribute master.



539
540
541
 
# File 'lib/mailchimp/api.rb', line 539

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

Parameters:

  • id (String) —

    the list id to pull abuse reports for (can be gathered using lists())

  • start (Int) (defaults to: 0) —

    optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)

  • limit (Int) (defaults to: 500) —

    optional for large data sets, the number of results to return - defaults to 500, upper limit set at 1000

  • since (String) (defaults to: nil) —

    optional pull only messages since this time - 24 hour format in <strong>GMT</strong>, eg “2013-12-30 20:30:00”

Returns:

  • (Hash) —

    the total of all reports and the specific reports reports this page

    • Int

      total the total number of matching abuse reports

    • Array

      data structs for the actual data for each reports, including:

      - [String] date date/time the abuse report was received and processed
- [String] email the email address that reported abuse
- [String] campaign_id the unique id for the campaign that report was made against
- [String] type an internal type generally specifying the orginating mail provider - may not be useful outside of filling report views



557
558
559
560
 
# File 'lib/mailchimp/api.rb', line 557

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.

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

Returns:

  • (Array) —

    of structs containing daily values, each containing:



565
566
567
568
 
# File 'lib/mailchimp/api.rb', line 565

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.

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • batch (Array) —

    an array of structs for each address using the following keys:

    • Hash

      email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Provide multiples and we’ll use the first we see in this same order.

      - [String] email an email address
- [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
- [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
    • String

      email_type for the email type option (html or text)

    • Hash

      merge_vars data for the various list specific and special merge vars documented in lists/subscribe

  • double_optin (Boolean) (defaults to: true) —

    flag to control whether to send an opt-in confirmation email - defaults to true

  • update_existing (Boolean) (defaults to: false) —

    flag to control whether to update members that are already subscribed to the list or to return an error, defaults to false (return error)

  • replace_interests (Boolean) (defaults to: true) —

    flag to determine whether we replace the interest groups with the updated groups provided, or we add the provided groups to the member’s interest groups (optional, defaults to true)

Returns:

  • (Hash) —

    struct of result counts and associated data

    • Int

      add_count Number of email addresses that were successfully added

    • Array

      adds array of structs for each add

      - [String] email the email address added
- [String] euid the email unique id
- [String] leid the list member's truly unique id
    • Int

      update_count Number of email addresses that were successfully updated

    • Array

      updates array of structs for each update

      - [String] email the email address added
- [String] euid the email unique id
- [String] leid the list member's truly unique id
    • Int

      error_count Number of email addresses that failed during addition/updating

    • Array

      errors array of error structs including:

      - [String] email whatever was passed in the batch record's email parameter
    - [String] email the email address added
    - [String] euid the email unique id
    - [String] leid the list member's truly unique id
- [Int] code the error code
- [String] error the full error message
- [Hash] row the row from the batch that caused the error



602
603
604
605
 
# File 'lib/mailchimp/api.rb', line 602

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • batch (Array) —

    array of structs to unsubscribe, each with one of the following keys - failing to provide anything will produce an error relating to the email address. Provide multiples and we’ll use the first we see in this same order.

    • String

      email an email address

    • String

      euid the unique id for an email address (not list related) - the email “id” returned from listMemberInfo, Webhooks, Campaigns, etc.

    • String

      leid the list email id (previously called web_id) for a list-member-info type call. this doesn’t change when the email address changes

  • delete_member (Boolean) (defaults to: false) —

    flag to completely delete the member from your list instead of just unsubscribing, default to false

  • send_goodbye (Boolean) (defaults to: true) —

    flag to send the goodbye email to the email addresses, defaults to true

  • send_notify (Boolean) (defaults to: false) —

    flag to send the unsubscribe notification email to the address defined in the list email notification settings, defaults to false

Returns:

  • (Array) —

    Array of structs containing results and any errors that occurred

    • Int

      success_count Number of email addresses that were successfully removed

    • Int

      error_count Number of email addresses that failed during addition/updating

    • Array

      of structs contain error details including:

    • Array

      errors array of error structs including:

      - [String] email whatever was passed in the batch record's email parameter
    - [String] email the email address added
    - [String] euid the email unique id
    - [String] leid the list member's truly unique id
- [Int] code the error code
- [String] error the full error message



627
628
629
630
 
# File 'lib/mailchimp/api.rb', line 627

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>

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

Returns:

  • (Hash) —

    the desktop and mobile user agents in use on the list

    • Hash

      desktop desktop user agents and percentages

      - [Double] penetration the percent of desktop clients in use
- [Array] clients array of structs for each client including:
    - [String] client the common name for the client
    - [String] icon a url to an image representing this client
    - [String] percent percent of list using the client
    - [String] members total members using the client
    • Hash

      mobile mobile user agents and percentages

      - [Double] penetration the percent of mobile clients in use
- [Array] clients array of structs for each client including:
    - [String] client the common name for the client
    - [String] icon a url to an image representing this client
    - [String] percent percent of list using the client
    - [String] members total members using the client



649
650
651
652
 
# File 'lib/mailchimp/api.rb', line 649

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.

Parameters:

  • id (String) (defaults to: nil) —

    optional - if provided, the list id to connect to. Get by calling lists/list. Otherwise the aggregate for the account.

Returns:

  • (Array) —

    array of structs containing months and growth data

    • String

      month The Year and Month in question using YYYY-MM format

    • Int

      existing number of existing subscribers to start the month

    • Int

      imports number of subscribers imported during the month

    • Int

      optins number of subscribers who opted-in during the month



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

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.

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • group_name (String) —

    the interest group to add - group names must be unique within a grouping

  • grouping_id (Int) (defaults to: nil) —

    optional The grouping to add the new group to - get using listInterestGrouping() . If not supplied, the first grouping on the list is used.

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



689
690
691
692
 
# File 'lib/mailchimp/api.rb', line 689

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.

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • group_name (String) —

    the interest group to delete

  • grouping_id (Int) (defaults to: nil) —

    The grouping to delete the group from - get using listInterestGrouping() . If not supplied, the first grouping on the list is used.

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



700
701
702
703
 
# File 'lib/mailchimp/api.rb', line 700

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • old_name (String) —

    the interest group name to be changed

  • new_name (String) —

    the new interest group name to be set

  • grouping_id (Int) (defaults to: nil) —

    optional The grouping to delete the group from - get using listInterestGrouping() . If not supplied, the first grouping on the list is used.

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



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

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.

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • name (String) —

    the interest grouping to add - grouping names must be unique

  • type (String) —

    The type of the grouping to add - one of “checkboxes”, “hidden”, “dropdown”, “radio”

  • groups (Array) —

    The lists of initial group names to be added - at least 1 is required and the names must be unique within a grouping. If the number takes you over the 60 group limit, an error will be thrown.

Returns:

  • (Hash) —

    with a single entry:

    • Int

      id the new grouping id if the request succeeds, otherwise an error will be thrown



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

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

Parameters:

  • grouping_id (Int) —

    the interest grouping id - get from listInterestGroupings()

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



733
734
735
736
 
# File 'lib/mailchimp/api.rb', line 733

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

Parameters:

  • grouping_id (Int) —

    the interest grouping id - get from listInterestGroupings()

  • name (String) —

    The name of the field to update - either “name” or “type”. Groups within the grouping should be manipulated using the standard listInterestGroup* methods

  • value (String) —

    The new value of the field. Grouping names must be unique - only “hidden” and “checkboxes” grouping types can be converted between each other.

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



744
745
746
747
 
# File 'lib/mailchimp/api.rb', line 744

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • counts (Bool) (defaults to: false) —

    optional whether or not to return subscriber counts for each group. defaults to false since that slows this call down a ton for large lists.

Returns:

  • (Array) —

    array of structs of the interest groupings for the list

    • Int

      id The id for the Grouping

    • String

      name Name for the Interest groups

    • String

      form_field Gives the type of interest group: checkbox,radio,select

    • Array

      groups Array structs of the grouping options (interest groups) including:

      - [String] bit the bit value - not really anything to be done with this
- [String] name the name of the group
- [String] display_order the display order of the group, if set
- [Int] subscribers total number of subscribers who have this group if "counts" is true. otherwise empty



678
679
680
681
 
# File 'lib/mailchimp/api.rb', line 678

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

Parameters:

  • filters (Hash) (defaults to: []) —

    filters to apply to this query - all are optional:

    • String

      list_id optional - return a single list using a known list_id. Accepts multiples separated by commas when not using exact matching

    • String

      list_name optional - only lists that match this name

    • String

      from_name optional - only lists that have a default from name matching this

    • String

      from_email optional - only lists that have a default from email matching this

    • String

      from_subject optional - only lists that have a default from email matching this

    • String

      created_before optional - only show lists that were created before this date/time - 24 hour format in <strong>GMT</strong>, eg “2013-12-30 20:30:00”

    • String

      created_after optional - only show lists that were created since this date/time - 24 hour format in <strong>GMT</strong>, eg “2013-12-30 20:30:00”

    • Boolean

      exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to true

  • start (Int) (defaults to: 0) —

    optional - control paging of lists, start results at this list #, defaults to 1st page of data (page 0)

  • limit (Int) (defaults to: 25) —

    optional - control paging of lists, number of lists to return with each call, defaults to 25 (max=100)

  • sort_field (String) (defaults to: 'created') —

    optional - “created” (the created date, default) or “web” (the display order in the web app). Invalid values will fall back on “created” - case insensitive.

  • sort_dir (String) (defaults to: 'DESC') —

    optional - “DESC” for descending (default), “ASC” for Ascending. Invalid values will fall back on “created” - case insensitive. Note: to get the exact display order as the web app you’d use “web” and “ASC”

Returns:

  • (Hash) —

    result of the operation including valid data and any errors

    • Int

      total the total number of lists which matched the provided filters

    • Array

      data structs for the lists which matched the provided filters, including the following

      - [String] id The list id for this list. This will be used for all other list management functions.
- [Int] web_id The list id used in our web app, allows you to create a link directly to it
- [String] name The name of the list.
- [String] date_created The date that this list was created.
- [Boolean] email_type_option Whether or not the List supports multiple formats for emails or just HTML
- [Boolean] use_awesomebar Whether or not campaigns for this list use the Awesome Bar in archives by default
- [String] default_from_name Default From Name for campaigns using this list
- [String] default_from_email Default From Email for campaigns using this list
- [String] default_subject Default Subject Line for campaigns using this list
- [String] default_language Default Language for this list's forms
- [Double] list_rating An auto-generated activity score for the list (0 - 5)
- [String] subscribe_url_short Our eepurl shortened version of this list's subscribe form (will not change)
- [String] subscribe_url_long The full version of this list's subscribe form (host will vary)
- [String] beamer_address The email address to use for this list's <a href="http://kb.mailchimp.com/article/how-do-i-import-a-campaign-via-email-email-beamer/">Email Beamer</a>
- [String] visibility Whether this list is Public (pub) or Private (prv). Used internally for projects like <a href="http://blog.mailchimp.com/introducing-wavelength/" target="_blank">Wavelength</a>
- [Hash] stats various stats and counts for the list - many of these are cached for at least 5 minutes
    - [Double] member_count The number of active members in the given list.
    - [Double] unsubscribe_count The number of members who have unsubscribed from the given list.
    - [Double] cleaned_count The number of members cleaned from the given list.
    - [Double] member_count_since_send The number of active members in the given list since the last campaign was sent
    - [Double] unsubscribe_count_since_send The number of members who have unsubscribed from the given list since the last campaign was sent
    - [Double] cleaned_count_since_send The number of members cleaned from the given list since the last campaign was sent
    - [Double] campaign_count The number of campaigns in any status that use this list
    - [Double] grouping_count The number of Interest Groupings for this list
    - [Double] group_count The number of Interest Groups (regardless of grouping) for this list
    - [Double] merge_var_count The number of merge vars for this list (not including the required EMAIL one)
    - [Double] avg_sub_rate the average number of subscribe per month for the list (empty value if we haven't calculated this yet)
    - [Double] avg_unsub_rate the average number of unsubscribe per month for the list (empty value if we haven't calculated this yet)
    - [Double] target_sub_rate the target subscription rate for the list to keep it growing (empty value if we haven't calculated this yet)
    - [Double] open_rate the average open rate per campaign for the list  (empty value if we haven't calculated this yet)
    - [Double] click_rate the average click rate per campaign for the list  (empty value if we haven't calculated this yet)
- [Array] modules Any list specific modules installed for this list (example is SocialPro)
    • Array

      errors structs of any errors found while loading lists - usually just from providing invalid list ids

      - [String] param the data that caused the failure
- [Int] code the error code
- [Int] error the error message



1262
1263
1264
1265
 
# File 'lib/mailchimp/api.rb', line 1262

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

Returns:

  • (Array) —

    array of locations

    • String

      country the country name

    • String

      cc the ISO 3166 2 digit country code

    • Double

      percent the percent of subscribers in the country

    • Double

      total the total number of subscribers in the country



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

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • emails (Array) —

    an array of up to 50 email structs, each with with one of the following keys

    • String

      email an email address - for new subscribers obviously this should be used

    • String

      euid the unique id for an email address (not list related) - the email “id” returned from listMemberInfo, Webhooks, Campaigns, etc.

    • String

      leid the list email id (previously called web_id) for a list-member-info type call. this doesn’t change when the email address changes

Returns:

  • (Hash) —

    of data and success/error counts

    • Int

      success_count the number of subscribers successfully found on the list

    • Int

      error_count the number of subscribers who were not found on the list

    • Array

      errors array of error structs including:

      - [String] email whatever was passed in the email parameter
    - [String] email the email address added
    - [String] euid the email unique id
    - [String] leid the list member's truly unique id
- [String] error the error message
- [String] code the error code
    • Array

      data an array of structs where each activity record has:

      - [String] email whatever was passed in the email parameter
    - [String] email the email address added
    - [String] euid the email unique id
    - [String] leid the list member's truly unique id
- [Array] activity an array of structs containing the activity, including:
    - [String] action The action name, one of: open, click, bounce, unsub, abuse, sent, queued, ecomm, mandrill_send, mandrill_hard_bounce, mandrill_soft_bounce, mandrill_open, mandrill_click, mandrill_spam, mandrill_unsub, mandrill_reject
    - [String] timestamp The date/time of the action (GMT)
    - [String] url For click actions, the url clicked, otherwise this is empty
    - [String] type If there's extra bounce, unsub, etc data it will show up here.
    - [String] campaign_id The campaign id the action was related to, if it exists - otherwise empty (ie, direct unsub from list)
    - [Hash] campaign_data If not deleted, the campaigns/list data for the campaign



789
790
791
792
 
# File 'lib/mailchimp/api.rb', line 789

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • emails (Array) —

    an array of up to 50 email structs, each with with one of the following keys

    • String

      email an email address - for new subscribers obviously this should be used

    • String

      euid the unique id for an email address (not list related) - the email “id” returned from listMemberInfo, Webhooks, Campaigns, etc.

    • String

      leid the list email id (previously called web_id) for a list-member-info type call. this doesn’t change when the email address changes

Returns:

  • (Hash) —

    of data and success/error counts

    • Int

      success_count the number of subscribers successfully found on the list

    • Int

      error_count the number of subscribers who were not found on the list

    • Array

      errors array of error structs including:

      - [Hash] email whatever was passed in the email parameter
    - [String] email the email address added
    - [String] euid the email unique id
    - [String] leid the list member's truly unique id
- [String] error the error message
    • Array

      data array of structs for each valid list member

      - [String] id The unique id (euid) for this email address on an account
- [String] email The email address associated with this record
- [String] email_type The type of emails this customer asked to get: html or text
- [Hash] merges a struct containing a key for each merge tags and the data for those tags for this email address, plus:
    - [Array] GROUPINGS if Interest groupings are enabled, this will exist with structs for each grouping:
        - [Int] id the grouping id
        - [String] name the interest group name
        - [Array] groups structs for each group in the grouping
            - [String] name the group name
            - [Bool] interested whether the member has this group selected
- [String] status The subscription status for this email address, either pending, subscribed, unsubscribed, or cleaned
- [String] ip_signup IP Address this address signed up from. This may be blank if single optin is used.
- [String] timestamp_signup The date/time the double optin was initiated. This may be blank if single optin is used.
- [String] ip_opt IP Address this address opted in from.
- [String] timestamp_opt The date/time the optin completed
- [Int] member_rating the rating of the subscriber. This will be 1 - 5 as described <a href="http://eepurl.com/f-2P" target="_blank">here</a>
- [String] campaign_id If the user is unsubscribed and they unsubscribed from a specific campaign, that campaign_id will be listed, otherwise this is not returned.
- [Array] lists An array of structs for the other lists this member belongs to
    - [String] id the list id
    - [String] status the members status on that list
- [String] timestamp The date/time this email address entered it's current status
- [String] info_changed The last time this record was changed. If the record is old enough, this may be blank.
- [Int] web_id The Member id used in our web app, allows you to create a link directly to it
- [Int] leid The Member id used in our web app, allows you to create a link directly to it
- [String] list_id The list id the for the member record being returned
- [String] list_name The list name the for the member record being returned
- [String] language if set/detected, a language code from <a href="http://kb.mailchimp.com/article/can-i-see-what-languages-my-subscribers-use#code" target="_blank">here</a>
- [Bool] is_gmonkey Whether the member is a <a href="http://mailchimp.com/features/golden-monkeys/" target="_blank">Golden Monkey</a> or not.
- [Hash] geo the geographic information if we have it. including:
    - [String] latitude the latitude
    - [String] longitude the longitude
    - [String] gmtoff GMT offset
    - [String] dstoff GMT offset during daylight savings (if DST not observered, will be same as gmtoff)
    - [String] timezone the timezone we've place them in
    - [String] cc 2 digit ISO-3166 country code
    - [String] region generally state, province, or similar
- [Hash] clients the client we've tracked the address as using with two keys:
    - [String] name the common name of the client
    - [String] icon_url a url representing a path to an icon representing this client
- [Array] static_segments structs for each static segments the member is a part of including:
    - [Int] id the segment id
    - [String] name the name given to the segment
    - [String] added the date the member was added
- [Array] notes structs for each note entered for this member. For each note:
    - [Int] id the note id
    - [String] note the text entered
    - [String] created the date the note was created
    - [String] updated the date the note was last updated
    - [String] created_by_name the name of the user who created the note. This can change as users update their profile.



859
860
861
862
 
# File 'lib/mailchimp/api.rb', line 859

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>

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • status (String) (defaults to: 'subscribed') —

    the status to get members for - one of(subscribed, unsubscribed, <a target=“_blank” href=“eepurl.com/gWOO”>cleaned</a>), defaults to subscribed

  • opts (Hash) (defaults to: []) —

    various options for controlling returned data

    • Int

      start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)

    • Int

      limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 100

    • String

      sort_field optional the data field to sort by - mergeX (1-30), your custom merge tags, “email”, “rating”,“last_update_time”, or “optin_time” - invalid fields will be ignored

    • String

      sort_dir optional the direct - ASC or DESC. defaults to ASC (case insensitive)

    • Hash

      segment a properly formatted segment that works with campaigns/segment-test

Returns:

  • (Hash) —

    of the total records matched and limited list member data for this page

    • Int

      total the total matching records

    • Array

      data structs for each member as returned by member-info



876
877
878
879
 
# File 'lib/mailchimp/api.rb', line 876

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • tag (String) —

    The merge tag to add, e.g. FNAME. 10 bytes max, valid characters: “A-Z 0-9 _” no spaces, dashes, etc. Some tags and prefixes are <a href=“kb.mailchimp.com/article/i-got-a-message-saying-that-my-list-field-name-is-reserved-and-cant-be-used” target=“_blank”>reserved</a>

  • name (String) —

    The long description of the tag being added, used for user displays - max 50 bytes

  • options (Array) (defaults to: []) —

    optional Various options for this merge var. note: for historical purposes this can also take a “boolean”

    • String

      field_type optional one of: text, number, radio, dropdown, date, address, phone, url, imageurl, zip, birthday - defaults to text

    • Boolean

      req optional indicates whether the field is required - defaults to false

    • Boolean

      public optional indicates whether the field is displayed in public - defaults to true

    • Boolean

      show optional indicates whether the field is displayed in the app’s list member view - defaults to true

    • Int

      order The order this merge tag should be displayed in - this will cause existing values to be reset so this fits

    • String

      default_value optional the default value for the field. See subscribe() for formatting info. Defaults to blank - max 255 bytes

    • String

      helptext optional the help text to be used with some newer forms. Defaults to blank - max 255 bytes

    • Array

      choices optional kind of - an array of strings to use as the choices for radio and dropdown type fields

    • String

      dateformat optional only valid for birthday and date fields. For birthday type, must be “MM/DD” (default) or “DD/MM”. For date type, must be “MM/DD/YYYY” (default) or “DD/MM/YYYY”. Any other values will be converted to the default.

    • String

      phoneformat optional “US” is the default - any other value will cause them to be unformatted (international)

    • String

      defaultcountry optional the <a href=“www.iso.org/iso/english_country_names_and_code_elements” target=“_blank”>ISO 3166 2 digit character code</a> for the default country. Defaults to “US”. Anything unrecognized will be converted to the default.

Returns:

  • (Hash) —

    the full data for the new merge var, just like merge-vars returns

    • String

      name Name/description of the merge field

    • Bool

      req Denotes whether the field is required (true) or not (false)

    • String

      field_type The “data type” of this merge var. One of: email, text, number, radio, dropdown, date, address, phone, url, imageurl

    • Bool

      public Whether or not this field is visible to list subscribers

    • Bool

      show Whether the field is displayed in thelist dashboard

    • String

      order The order this field displays in on forms

    • String

      default The default value for this field

    • String

      helptext The helptext for this field

    • String

      size The width of the field to be used

    • String

      tag The merge tag that’s used for forms and subscribe() and updateMember()

    • Array

      choices the options available for radio and dropdown field types

    • Int

      id an unchanging id for the merge var



910
911
912
913
 
# File 'lib/mailchimp/api.rb', line 910

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.

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • tag (String) —

    The merge tag to delete

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



920
921
922
923
 
# File 'lib/mailchimp/api.rb', line 920

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.

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • tag (String) —

    The merge tag to reset

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



930
931
932
933
 
# File 'lib/mailchimp/api.rb', line 930

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.

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • tag (String) —

    The merge tag to reset

  • value (String) —

    The value to set - see subscribe() for formatting. Must validate to something non-empty.

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



941
942
943
944
 
# File 'lib/mailchimp/api.rb', line 941

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • tag (String) —

    The merge tag to update

  • options (Hash) —

    The options to change for a merge var. See listMergeVarAdd() for valid options. “tag” and “name” may also be used here.

Returns:

  • (Hash) —

    the full data for the new merge var, just like merge-vars returns

    • String

      name Name/description of the merge field

    • Bool

      req Denotes whether the field is required (true) or not (false)

    • String

      field_type The “data type” of this merge var. One of: email, text, number, radio, dropdown, date, address, phone, url, imageurl

    • Bool

      public Whether or not this field is visible to list subscribers

    • Bool

      show Whether the field is displayed in thelist dashboard

    • String

      order The order this field to displays in on forms

    • String

      default The default value for this field

    • String

      helptext The helptext for this field

    • String

      size The width of the field to be used

    • String

      tag The merge tag that’s used for forms and subscribe() and updateMember()

    • Array

      choices the options available for radio and dropdown field types

    • Int

      id an unchanging id for the merge var



963
964
965
966
 
# File 'lib/mailchimp/api.rb', line 963

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

Parameters:

  • id (Array) —

    the list ids to retrieve merge vars for. Get by calling lists() - max of 100

Returns:

  • (Hash) —

    of data and success/error counts

    • Int

      success_count the number of subscribers successfully found on the list

    • Int

      error_count the number of subscribers who were not found on the list

    • Array

      data of structs for the merge tags on each list

      - [String] id the list id
- [String] name the list name
- [Array] merge_vars of structs for each merge var
    - [String] name Name of the merge field
    - [Bool] req Denotes whether the field is required (true) or not (false)
    - [String] field_type The "data type" of this merge var. One of the options accepted by field_type in lists/merge-var-add
    - [Bool] public Whether or not this field is visible to list subscribers
    - [Bool] show Whether the list owner has this field displayed on their list dashboard
    - [String] order The order the list owner has set this field to display in
    - [String] default The default value the list owner has set for this field
    - [String] helptext The helptext for this field
    - [String] size The width of the field to be used
    - [String] tag The merge tag that's used for forms and listSubscribe() and listUpdateMember()
    - [Array] choices For radio and dropdown field types, an array of the options available
    - [Int] id an unchanging id for the merge var
    • Array

      errors of error structs

      - [String] id the passed list id that failed
- [Int] code the resulting error code
- [String] msg the resulting error message



993
994
995
996
 
# File 'lib/mailchimp/api.rb', line 993

def merge_vars(id)
    _params = {:id => id}
    return @master.call 'lists/merge-vars', _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.

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • name (String) —

    a unique name per list for the segment - 100 byte maximum length, anything longer will throw an error

Returns:

  • (Hash) —

    with a single entry:

    • Int

      id the id of the new segment, otherwise an error will be thrown.



1003
1004
1005
1006
 
# File 'lib/mailchimp/api.rb', line 1003

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • seg_id (Int) —

    the id of the static segment to delete - get from listStaticSegments()

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



1013
1014
1015
1016
 
# File 'lib/mailchimp/api.rb', line 1013

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!

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • seg_id (Int) —

    the id of the static segment to modify - get from listStaticSegments()

  • batch (Array) —

    an array of structs for each address using the following keys:

    • Hash

      email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Provide multiples and we’ll use the first we see in this same order.

      - [String] email an email address
- [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
- [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes

Returns:

  • (Hash) —

    an array with the results of the operation

    • Int

      success_count the total number of successful updates (will include members already in the segment)

    • Array

      errors structs for each error including:

      - [String] email whatever was passed in the email parameter
    - [String] email the email address added
    - [String] euid the email unique id
    - [String] leid the list member's truly unique id
- [String] code the error code
- [String] error the full error message



1035
1036
1037
1038
 
# File 'lib/mailchimp/api.rb', line 1035

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!

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • seg_id (Int) —

    the id of the static segment to delete - get from listStaticSegments()

  • batch (Array) —

    an array of structs for each address using the following keys:

    • Hash

      email a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Provide multiples and we’ll use the first we see in this same order.

      - [String] email an email address
- [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
- [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes

Returns:

  • (Hash) —

    an array with the results of the operation

    • Int

      success_count the total number of successful removals

    • Int

      error_count the total number of unsuccessful removals

    • Array

      errors structs for each error including:

      - [String] email whatever was passed in the email parameter
    - [String] email the email address added
    - [String] euid the email unique id
    - [String] leid the list member's truly unique id
- [String] code the error code
- [String] error the full error message



1058
1059
1060
1061
 
# File 'lib/mailchimp/api.rb', line 1058

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • seg_id (Int) —

    the id of the static segment to reset - get from listStaticSegments()

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



1068
1069
1070
1071
 
# File 'lib/mailchimp/api.rb', line 1068

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.

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

Returns:

  • (Array) —

    an of structs with data for each static segment

    • Int

      id the id of the segment

    • String

      name the name for the segment

    • Int

      member_count the total number of subscribed members currently in a segment

    • String

      created_date the date/time the segment was created

    • String

      last_update the date/time the segment was last updated (add or del)

    • String

      last_reset the date/time the segment was last reset (ie had all members cleared from it)



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

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!

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists/list()

  • email (Hash) —

    a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Providing multiples and will use the first we see in this same order.

    • String

      email an email address - for new subscribers obviously this should be used

    • String

      euid the unique id for an email address (not list related) - the email “id” returned from listMemberInfo, Webhooks, Campaigns, etc.

    • String

      leid the list email id (previously called web_id) for a list-member-info type call. this doesn’t change when the email address changes

  • merge_vars (Hash) (defaults to: nil) —

    optional merges for the email (FNAME, LNAME, <a href=“kb.mailchimp.com/article/where-can-i-find-my-lists-merge-tags target=”_blank“>etc.</a>) (see examples below for handling ”blank“ arrays). Note that a merge field can only hold up to 255 bytes. Also, there are a few ”special“ keys:

    • String

      new-email set this to change the email address. This is only respected on calls using update_existing or when passed to listUpdateMember().

    • Array

      groupings of Interest Grouping structs. Each should contain:

      - [Int] id Grouping "id" from lists/interest-groupings (either this or name must be present) - this id takes precedence and can't change (unlike the name)
- [String] name Grouping "name" from lists/interest-groupings (either this or id must be present)
- [Array] groups an array of valid group names for this grouping.
    • String

      optin_ip Set the Opt-in IP field. Abusing this may cause your account to be suspended. We do validate this and it must not be a private IP address.

    • String

      optin_time Set the Opt-in Time field. Abusing this may cause your account to be suspended. We do validate this and it must be a valid date. Use - 24 hour format in <strong>GMT</strong>, eg “2013-12-30 20:30:00” to be safe. Generally, though, anything strtotime() understands we’ll understand - <a href=“us2.php.net/strtotime” target=“_blank”>us2.php.net/strtotime</a>

    • Hash

      mc_location Set the member’s geographic location either by optin_ip or geo data.

      - [String] latitude use the specified latitude (longitude must exist for this to work)
- [String] longitude use the specified longitude (latitude must exist for this to work)
- [String] anything if this (or any other key exists here) we'll try to use the optin ip. NOTE - this will slow down each subscribe call a bit, especially for lat/lng pairs in sparsely populated areas. Currently our automated background processes can and will overwrite this based on opens and clicks.
    • String

      mc_language Set the member’s language preference. Supported codes are fully case-sensitive and can be found <a href=“kb.mailchimp.com/article/can-i-see-what-languages-my-subscribers-use#code” target=“_new”>here</a>.

    • Array

      mc_notes of structs for managing notes - it may contain:

      - [String] note the note to set. this is required unless you're deleting a note
- [Int] id the note id to operate on. not including this (or using an invalid id) causes a new note to be added
- [String] action if the "id" key exists and is valid, an "update" key may be set to "append" (default), "prepend", "replace", or "delete" to handle how we should update existing notes. "delete", obviously, will only work with a valid "id" - passing that along with "note" and an invalid "id" is wrong and will be ignored.
  • email_type (String) (defaults to: 'html') —

    optional email type preference for the email (html or text - defaults to html)

  • double_optin (Bool) (defaults to: true) —

    optional flag to control whether a double opt-in confirmation message is sent, defaults to true. Abusing this may cause your account to be suspended.

  • update_existing (Bool) (defaults to: false) —

    optional flag to control whether existing subscribers should be updated instead of throwing an error, defaults to false

  • replace_interests (Bool) (defaults to: true) —

    optional flag to determine whether we replace the interest groups with the groups provided or we add the provided groups to the member’s interest groups (optional, defaults to true)

  • send_welcome (Bool) (defaults to: false) —

    optional if your double_optin is false and this is true, we will send your lists Welcome Email if this subscribe succeeds - this will not fire if we end up updating an existing subscriber. If double_optin is true, this has no effect. defaults to false.

Returns:

  • (Hash) —

    the ids for this subscriber

    • String

      email the email address added

    • String

      euid the email unique id

    • String

      leid the list member’s truly unique id



1119
1120
1121
1122
 
# File 'lib/mailchimp/api.rb', line 1119

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • email (Hash) —

    a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Providing multiples and will use the first we see in this same order.

    • String

      email an email address

    • String

      euid the unique id for an email address (not list related) - the email “id” returned from listMemberInfo, Webhooks, Campaigns, etc.

    • String

      leid the list email id (previously called web_id) for a list-member-info type call. this doesn’t change when the email address changes

  • delete_member (Boolean) (defaults to: false) —

    flag to completely delete the member from your list instead of just unsubscribing, default to false

  • send_goodbye (Boolean) (defaults to: true) —

    flag to send the goodbye email to the email address, defaults to true

  • send_notify (Boolean) (defaults to: true) —

    flag to send the unsubscribe notification email to the address defined in the list email notification settings, defaults to true

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



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

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 listBatchSubscribe() with the update_existing and possible replace_interests parameter.

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • email (Hash) —

    a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. Providing multiples and will use the first we see in this same order.

    • String

      email an email address

    • String

      euid the unique id for an email address (not list related) - the email “id” returned from listMemberInfo, Webhooks, Campaigns, etc.

    • String

      leid the list email id (previously called web_id) for a list-member-info type call. this doesn’t change when the email address changes

  • merge_vars (Array) —

    array of new field values to update the member with. See merge_vars in listSubscribe() for details.

  • email_type (String) (defaults to: '') —

    change the email type preference for the member (“html” or “text”). Leave blank to keep the existing preference (optional)

  • replace_interests (Boolean) (defaults to: true) —

    flag to determine whether we replace the interest groups with the updated groups provided, or we add the provided groups to the member’s interest groups (optional, defaults to true)

Returns:

  • (Hash) —

    the ids for this subscriber

    • String

      email the email address added

    • String

      euid the email unique id

    • String

      leid the list member’s truly unique id



1153
1154
1155
1156
 
# File 'lib/mailchimp/api.rb', line 1153

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • url (String) —

    a valid URL for the Webhook - it will be validated. note that a url may only exist on a list once.

  • actions (Hash) (defaults to: []) —

    optional a hash of actions to fire this Webhook for

    • Bool

      subscribe optional as subscribes occur, defaults to true

    • Bool

      unsubscribe optional as subscribes occur, defaults to true

    • Bool

      profile optional as profile updates occur, defaults to true

    • Bool

      cleaned optional as emails are cleaned from the list, defaults to true

    • Bool

      upemail optional when subscribers change their email address, defaults to true

    • Bool

      campaign option when a campaign is sent or canceled, defaults to true

  • sources (Hash) (defaults to: []) —

    optional sources to fire this Webhook for

    • Bool

      user optional user/subscriber initiated actions, defaults to true

    • Bool

      admin optional admin actions in our web app, defaults to true

    • Bool

      api optional actions that happen via API calls, defaults to false

Returns:

  • (Hash) —

    with a single entry:

    • Int

      id the id of the new webhook, otherwise an error will be thrown.



1174
1175
1176
1177
 
# File 'lib/mailchimp/api.rb', line 1174

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

  • url (String) —

    the URL of a Webhook on this list

Returns:

  • (Hash) —

    with a single entry:

    • Bool

      complete whether the call worked. reallistically this will always be true as errors will be thrown otherwise.



1184
1185
1186
1187
 
# File 'lib/mailchimp/api.rb', line 1184

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

Parameters:

  • id (String) —

    the list id to connect to. Get by calling lists()

Returns:

  • (Array) —

    of structs for each webhook

    • String

      url the URL for this Webhook

    • Hash

      actions the possible actions and whether they are enabled

      - [Bool] subscribe triggered when subscribes happen
- [Bool] unsubscribe triggered when unsubscribes happen
- [Bool] profile triggered when profile updates happen
- [Bool] cleaned triggered when a subscriber is cleaned (bounced) from a list
- [Bool] upemail triggered when a subscriber's email address is changed
- [Bool] campaign triggered when a campaign is sent or canceled
    • Hash

      sources the possible sources and whether they are enabled

      - [Bool] user whether user/subscriber triggered actions are returned
- [Bool] admin whether admin (manual, in-app) triggered actions are returned
- [Bool] api whether api triggered actions are returned



1204
1205
1206
1207
 
# File 'lib/mailchimp/api.rb', line 1204

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