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.



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

Parameters:

  • id (String) —

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

  • 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 originating mail provider - may not be useful outside of filling report views



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.

Parameters:

  • id (String) —

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

Returns:

  • (Array) —

    of structs containing daily values, each containing:



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.

Parameters:

  • id (String) —

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

  • 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



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

Parameters:

  • id (String) —

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

  • 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



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>

Parameters:

  • id (String) —

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

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



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.

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



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.

Parameters:

  • id (String) —

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

  • 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 lists/interest-groupings() . 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.



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.

Parameters:

  • id (String) —

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

  • group_name (String) —

    the interest group to delete

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

    The grouping to delete the group from - get using lists/interest-groupings() . 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.



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

Parameters:

  • id (String) —

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

  • 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 lists/interest-groupings() . 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.



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.

Parameters:

  • id (String) —

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

  • 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



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

Parameters:

  • grouping_id (Int) —

    the interest grouping id - get from lists/interest-groupings()

Returns:

  • (Hash) —

    with a single entry:

    • Bool

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



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

Parameters:

  • grouping_id (Int) —

    the interest grouping id - get from lists/interest-groupings()

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



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

Parameters:

  • id (String) —

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

  • 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



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

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



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

Parameters:

  • id (String) —

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

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



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

Parameters:

  • id (String) —

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

  • 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



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

Parameters:

  • id (String) —

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

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



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>

Parameters:

  • id (String) —

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

  • 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



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

Parameters:

  • id (String) —

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

  • 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 (Hash) (defaults to: []) —

    optional Various options for this merge var

    • 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 lists/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 lists/subscribe() and lists/update-member()

    • Array

      choices the options available for radio and dropdown field types

    • Int

      id an unchanging id for the merge var



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.

Parameters:

  • id (String) —

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

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



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.

Parameters:

  • id (String) —

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

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



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.

Parameters:

  • id (String) —

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

  • tag (String) —

    The merge tag to reset

  • value (String) —

    The value to set - see lists/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.



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

Parameters:

  • id (String) —

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

  • tag (String) —

    The merge tag to update

  • options (Hash) —

    The options to change for a merge var. See lists/merge-var-add() 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 lists/subscribe() and lists/update-member()

    • Array

      choices the options available for radio and dropdown field types

    • Int

      id an unchanging id for the merge var



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

Parameters:

  • id (Array) —

    the list ids to retrieve merge vars for. Get by calling lists/list() - 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 lists/subscribe() 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



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.

Parameters:

  • id (String) —

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

  • opts (Hash) —

    various options for the new segment

    • String

      type either “static” or “saved”

    • String

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

    • Hash

      segment_opts for “saved” only, the standard segment match+conditions, just like campaigns/segment-test

      - [String] match "any" or "all"
- [Array] conditions structs for each condition, just like campaigns/segment-test

Returns:

  • (Hash) —

    with a single entry:

    • Int

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



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

Parameters:

  • id (String) —

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

  • seg_id (Int) —

    the id of the static segment to delete - get from lists/static-segments()

Returns:

  • (Hash) —

    with a single entry:

    • Bool

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



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.

Parameters:

  • list_id (String) —

    the list to test segmentation on - get lists using lists/list()

  • options (Hash) —

    with 1 or 2 keys:

    • String

      saved_segment_id a saved segment id from lists/segments() - this will take precendence, otherwise the match+conditions are required.

    • String

      match controls whether to use AND or OR when applying your options - expects “<strong>any</strong>” (for OR) or “<strong>all</strong>” (for AND)

    • Array

      conditions of up to 5 structs for different criteria to apply while segmenting. Each criteria row must contain 3 keys - “<strong>field</strong>”, “<strong>op</strong>”, and “<strong>value</strong>” - and possibly a fourth, “<strong>extra</strong>”, based on these definitions:

Returns:

  • (Hash) —

    with a single entry:

    • Int

      total The total number of subscribers matching your segmentation options



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.

Parameters:

  • id (String) —

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

  • seg_id (Int) —

    the segment to updated. Get by calling lists/segments()

  • opts (Hash) —

    various options to update

    • String

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

    • Hash

      segment_opts for “saved” only, the standard segment match+conditions, just like campaigns/segment-test

      - [Hash] match "any" or "all"
- [Array] conditions structs for each condition, just like campaigns/segment-test

Returns:

  • (Hash) —

    with a single entry:

    • Bool

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



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.

Parameters:

  • id (String) —

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

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

    optional, if specified should be “static” or “saved” and will limit the returned entries to that type

Returns:

  • (Hash) —

    with 2 keys:

    • Int

      static.id the id of the 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)



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.

Parameters:

  • id (String) —

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

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



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

Parameters:

  • id (String) —

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

  • seg_id (Int) —

    the id of the static segment to delete - get from lists/static-segments()

Returns:

  • (Hash) —

    with a single entry:

    • Bool

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



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!

Parameters:

  • id (String) —

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

  • seg_id (Int) —

    the id of the static segment to modify - get from lists/static-segments()

  • batch (Array) —

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

    • 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



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!

Parameters:

  • id (String) —

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

  • seg_id (Int) —

    the id of the static segment to delete - get from lists/static-segments()

  • batch (Array) —

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

    • 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



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

Parameters:

  • id (String) —

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

  • seg_id (Int) —

    the id of the static segment to reset - get from lists/static-segments()

Returns:

  • (Hash) —

    with a single entry:

    • Bool

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



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.

Parameters:

  • id (String) —

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

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)



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!

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



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

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

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



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.

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

    • 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 lists/subscribe() 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



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

Parameters:

  • id (String) —

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

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



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

Parameters:

  • id (String) —

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

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



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

Parameters:

  • id (String) —

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

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



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

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