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.



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

def initialize(master)
    @master = master
end

Instance Attribute Details

#master ⇒ Object

Returns the value of attribute master.



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

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 GMT, 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


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

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:



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

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


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

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


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

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 user-agent-string.info

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


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

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


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

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.


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

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.


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

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.


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

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


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

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.


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

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.


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

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


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

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 GMT, 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 GMT, 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 Email Beamer
      • [String] visibility Whether this list is Public (pub) or Private (prv). Used internally for projects like Wavelength
      • [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


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

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


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

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 address struct to retrieve activity information for

    • [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) —

    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


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

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 address struct to retrieve member information for

    • [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) —

    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 here
      • [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 here
      • [Bool] is_gmonkey Whether the member is a Golden Monkey 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.


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

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 List Export API

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, cleaned), 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


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

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 reserved

  • 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 ISO 3166 2 digit character code 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


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

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.


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

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.


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

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.


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

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


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

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


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

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 are not 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 - 50 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.


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

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.


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

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 will not 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


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

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 will not 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


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

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


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

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)


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

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="http://kb.mailchimp.com/article/where-can-i-find-my-lists-merge-tags target="_blank">etc.) (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 GMT, eg "2013-12-30 20:30:00" to be safe. Generally, though, anything strtotime() understands we'll understand - http://us2.php.net/strtotime
    • [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 here.
    • [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


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

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.


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

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


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

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.


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

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.


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

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


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

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