hominid 2.0.2 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. data/.gitignore +1 -0
  2. data/README.rdoc +118 -0
  3. data/VERSION +1 -1
  4. data/hominid.gemspec +4 -4
  5. data/lib/hominid/base.rb +4 -8
  6. data/lib/hominid/campaign.rb +485 -500
  7. data/lib/hominid/helper.rb +64 -71
  8. data/lib/hominid/list.rb +254 -268
  9. data/lib/hominid/security.rb +27 -29
  10. metadata +4 -4
  11. data/README.textile +0 -118
data/lib/hominid/helper.rb CHANGED
@@ -1,93 +1,86 @@
1
1
  module Hominid
2
2
  module Helper
3
3
 
4
- # HELPER METHODS
5
-
4
+ # Retrieve lots of account information including payments made, plan info,
5
+ # some account stats, installed modules, contact info, and more. No private
6
+ # information like Credit Card numbers is available.
7
+ #
8
+ # Parameters:
9
+ # * options (Hash) =
10
+ #
11
+ # Returns:
12
+ # An array of account details for this API key including:
13
+ # * username (String) = The Account username.
14
+ # * user_id (String) = The Account user unique id (for building some links).
15
+ # * is_trial (Boolean) = Whether the Account is in Trial mode.
16
+ # * timezone (String) = The timezone for the Account.
17
+ # * plan_type (String) = Plan Type - "monthly", "payasyougo", or "free".
18
+ # * plan_low (Integer) = Only for Monthly plans - the lower tier for list size.
19
+ # * plan_high (Integer) = Only for Monthly plans - the upper tier for list size.
20
+ # * plan_start_date (DateTime) = Only for Monthly plans - the start date for a monthly plan.
21
+ # * emails_left (Integer) = Only for Free and Pay-as-you-go plans emails credits left for the account.
22
+ # * pending_monthly (Boolean) = Whether the account is finishing Pay As You Go credits before switching to a Monthly plan.
23
+ # * first_payment (DateTime) = Date of first payment.
24
+ # * last_payment (DateTime) = Date of most recent payment.
25
+ # * times_logged_in (Integer) = Total number of times the account has been logged into via the web.
26
+ # * last_login (DateTime) = Date/time of last login via the web.
27
+ # * affiliate_link (String) = Monkey Rewards link for our Affiliate program.
28
+ # * contact (Array) = Contact details for the account, including: First & Last name, email, company name, address, phone, and url.
29
+ # * addons (Array) = Addons installed in the account and the date they were installed.
30
+ # * orders (Array) = Order details for the account, include order_id, type, cost, date/time, and any credits applied to the order.
31
+ #
6
32
  def account_details
7
- # Retrieve lots of account information including payments made, plan info,
8
- # some account stats, installed modules, contact info, and more. No private
9
- # information like Credit Card numbers is available.
10
- #
11
- # Parameters:
12
- # options (Hash) =
13
- #
14
- # Returns:
15
- # An array of account details for this API key including:
16
- # username (String) = The Account username.
17
- # user_id (String) = The Account user unique id (for building some links).
18
- # is_trial (Boolean) = Whether the Account is in Trial mode.
19
- # timezone (String) = The timezone for the Account.
20
- # plan_type (String) = Plan Type - "monthly", "payasyougo", or "free".
21
- # plan_low (Integer) = Only for Monthly plans - the lower tier for list size.
22
- # plan_high (Integer) = Only for Monthly plans - the upper tier for list size.
23
- # plan_start_date (DateTime) = Only for Monthly plans - the start date for a monthly plan.
24
- # emails_left (Integer) = Only for Free and Pay-as-you-go plans emails credits left for the account.
25
- # pending_monthly (Boolean) = Whether the account is finishing Pay As You Go credits before switching to
26
- # a Monthly plan.
27
- # first_payment (DateTime) = Date of first payment.
28
- # last_payment (DateTime) = Date of most recent payment.
29
- # times_logged_in (Integer) = Total number of times the account has been logged into via the web.
30
- # last_login (DateTime) = Date/time of last login via the web.
31
- # affiliate_link (String) = Monkey Rewards link for our Affiliate program.
32
- # contact (Array) = Contact details for the account, including: First & Last name, email, company
33
- # name, address, phone, and url.
34
- # addons (Array) = Addons installed in the account and the date they were installed.
35
- # orders (Array) = Order details for the account, include order_id, type, cost, date/time, and any
36
- # credits applied to the order.
37
- #
38
33
  hash_to_object(call("getAccountDetails"))
39
34
  end
40
-
41
- def inline_css(html, strip_css = false)
42
- # Send your HTML content to have the CSS inlined and optionally remove the original styles.
43
- #
44
- # Paramters:
45
- # html (String) = Your HTML content.
46
- # strip_css (Boolean) = Whether you want the CSS <style> tags stripped from the returned document. Defaults to false.
47
- #
48
- # Returns:
49
- # Your HTML content with all CSS inlined, just like if we sent it. (String)
50
- #
35
+
36
+ # Send your HTML content to have the CSS inlined and optionally remove the original styles.
37
+ #
38
+ # Paramters:
39
+ # * html (String) = Your HTML content.
40
+ # * strip_css (Boolean) = Whether you want the CSS <style> tags stripped from the returned document. Defaults to false.
41
+ #
42
+ # Returns:
43
+ # Your HTML content with all CSS inlined, just like if we sent it. (String)
44
+ #
45
+ def inline_css(html, strip_css = false)
51
46
  call("inlineCss", html, strip_css)
52
47
  end
53
48
  alias :convert_css_to_inline :inline_css
54
49
 
50
+ # Create a new folder to file campaigns in.
51
+ #
52
+ # Parameters:
53
+ # * name (String) = A unique name for a folder.
54
+ #
55
+ # Returns:
56
+ # The folder_id of the newly created folder. (Integer)
55
57
  def create_folder(name)
56
- # Create a new folder to file campaigns in.
57
- #
58
- # Parameters:
59
- # name (String) = A unique name for a folder.
60
- #
61
- # Returns:
62
- # The folder_id of the newly created folder. (Integer)
63
58
  call("createFolder", name)
64
59
  end
65
60
 
61
+ # Have HTML content auto-converted to a text-only format. You can send: plain HTML, an array of Template content,
62
+ # an existing Campaign Id, or an existing Template Id. Note that this will not save anything to or update any of
63
+ # your lists, campaigns, or templates.
64
+ #
65
+ # Parameters:
66
+ # * type (String) = Must be one of: "html", "template", "url", "cid", or "tid".
67
+ # * content (String) = The content to use. For "html" expects a single string value, "template" expects an array like you send to campaignCreate, "url" expects a valid & public URL to pull from, "cid" expects a valid Campaign Id, and "tid" expects a valid Template Id on your account.
68
+ #
69
+ # Returns:
70
+ # The content passed in converted to text. (String)
71
+ #
66
72
  def generate_text(type, content)
67
- # Have HTML content auto-converted to a text-only format. You can send: plain HTML, an array of Template content,
68
- # an existing Campaign Id, or an existing Template Id. Note that this will not save anything to or update any of
69
- # your lists, campaigns, or templates.
70
- #
71
- # Parameters:
72
- # type (String) = Must be one of: "html", "template", "url", "cid", or "tid".
73
- # content (String) = The content to use. For "html" expects a single string value, "template" expects an array
74
- # like you send to campaignCreate, "url" expects a valid & public URL to pull from, "cid"
75
- # expects a valid Campaign Id, and "tid" expects a valid Template Id on your account.
76
- #
77
- # Returns:
78
- # The content passed in converted to text. (String)
79
- #
80
73
  call("generateText", type, content)
81
74
  end
82
75
 
76
+ # "Ping" the MailChimp API - a simple method you can call that will return a constant value as long as everything
77
+ # is good. Note than unlike most all of our methods, we don't throw an Exception if we are having issues. You will
78
+ # simply receive a different string back that will explain our view on what is going on.
79
+ #
80
+ # Returns:
81
+ # "Everything's Chimpy!"
82
+ #
83
83
  def ping(options = {})
84
- # "Ping" the MailChimp API - a simple method you can call that will return a constant value as long as everything
85
- # is good. Note than unlike most all of our methods, we don't throw an Exception if we are having issues. You will
86
- # simply receive a different string back that will explain our view on what is going on.
87
- #
88
- # Returns:
89
- # "Everything's Chimpy!"
90
- #
91
84
  call("ping")
92
85
  end
93
86
 
data/lib/hominid/list.rb CHANGED
@@ -1,285 +1,273 @@
1
1
  module Hominid
2
2
  module List
3
3
 
4
- # LIST RELATED METHODS
5
-
4
+ # Get all the lists for this account.
6
5
  def lists
7
- # Get all the lists for this account.
8
6
  call("lists")
9
7
  end
10
8
 
9
+ # Find a mailing list by name
11
10
  def find_list_by_name(list_name)
12
- # Find a mailing list by name
13
11
  call("lists").find {|list| list["name"] == list_name}
14
12
  end
15
13
 
14
+ # Find a mailing list ID by name
16
15
  def find_list_id_by_name(list_name)
17
- # Find a mailing list ID by name
18
16
  call("lists").find {|list| list["name"] == list_name}["id"]
19
17
  end
20
18
 
19
+ # Find a mailing list by ID
21
20
  def find_list_by_id(list_id)
22
- # Find a mailing list by ID
23
21
  call("lists").find {|list| list["id"] == list_id}
24
22
  end
25
23
 
24
+ # Find a mailing list by web_id
26
25
  def find_list_by_web_id(list_web_id)
27
- # Find a mailing list by web_id
28
26
  call("lists").find {|list| list["web_id"] == list_web_id}
29
27
  end
30
28
 
29
+ # Find a mailing list ID by web_id
31
30
  def find_list_id_by_web_id(list_web_id)
32
- # Find a mailing list ID by web_id
33
31
  call("lists").find {|list| list["web_id"] == list_web_id}["id"]
34
32
  end
35
-
33
+
34
+ # Get all email addresses that complained about a given list.
35
+ #
36
+ # Parameters:
37
+ # * list_id (String) = The mailing list ID value.
38
+ # * list_id (String) = The mailing list ID value.
39
+ # * start (Integer) = Page number to start at. Defaults to 0.
40
+ # * limit (Integer) = Number of results to return. Defaults to 500. Upper limit is 1000.
41
+ # * since (DateTime) = Only return email reports since this date. Must be in YYYY-MM-DD HH:II:SS format (GMT).
42
+ #
43
+ # Returns:
44
+ # An array of abuse reports for this list including:
45
+ # * date (String) = Date/time the abuse report was received and processed.
46
+ # * email (String) = The email address that reported abuse.
47
+ # * campaign_id (String) = The unique id for the campaign that report was made against.
48
+ # * type (String) = An internal type generally specifying the orginating mail provider - may not be useful outside of filling report views.
49
+ #
36
50
  def list_abuse_reports(list_id, start = 0, limit = 500, since = "2000-01-01 00:00:00")
37
- # Get all email addresses that complained about a given list.
38
- #
39
- # Parameters:
40
- # list_id (String) = The mailing list ID value.
41
- # list_id (String) = The mailing list ID value.
42
- # start (Integer) = Page number to start at. Defaults to 0.
43
- # limit (Integer) = Number of results to return. Defaults to 500. Upper limit is 1000.
44
- # since (DateTime) = Only return email reports since this date. Must be in YYYY-MM-DD HH:II:SS format (GMT).
45
- #
46
- # Returns:
47
- # An array of abuse reports for this list including:
48
- # date (String) = Date/time the abuse report was received and processed.
49
- # email (String) = The email address that reported abuse.
50
- # campaign_id (String) = The unique id for the campaign that report was made against.
51
- # type (String) = An internal type generally specifying the orginating mail provider - may not be
52
- # useful outside of filling report views.
53
- #
54
51
  call("listAbuseReports", list_id, start, limit, since)
55
52
  end
56
53
 
54
+ # Add a single Interest Group - if interest groups for the List are not yet
55
+ # enabled, adding the first group will automatically turn them on.
56
+ #
57
+ # Parameters:
58
+ # * list_id (String) = The mailing list ID value.
59
+ # * group (String) = The interest group to add.
60
+ #
61
+ # Returns:
62
+ # True if successful, error code if not.
63
+ #
57
64
  def create_group(list_id, group)
58
- # Add a single Interest Group - if interest groups for the List are not yet
59
- # enabled, adding the first group will automatically turn them on.
60
- #
61
- # Parameters:
62
- # list_id (String) = The mailing list ID value.
63
- # group (String) = The interest group to add.
64
- #
65
- # Returns:
66
- # True if successful, error code if not.
67
- #
68
65
  call("listInterestGroupAdd", list_id, group)
69
66
  end
70
67
  alias :interest_group_add :create_group
71
68
 
69
+ # Add a new merge tag to a given list
70
+ #
71
+ # Parameters:
72
+ # * list_id (String) = The mailing list ID value.
73
+ # * tag (String) = The merge tag to add. Ex: FNAME
74
+ # * name (String) = The long description of the tag being added, used for user displays.
75
+ # * required (Boolean) = TODO: set this up to accept the options available.
76
+ #
77
+ # Returns:
78
+ # True if successful, error code if not.
79
+ #
72
80
  def create_tag(list_id, tag, name, required = false)
73
- # Add a new merge tag to a given list
74
- #
75
- # Parameters:
76
- # list_id (String) = The mailing list ID value.
77
- # tag (String) = The merge tag to add. Ex: FNAME
78
- # name (String) = The long description of the tag being added, used for user displays.
79
- # required (Boolean) = TODO: set this up to accept the options available.
80
- #
81
- # Returns:
82
- # True if successful, error code if not.
83
- #
84
81
  call("listMergeVarAdd", list_id, tag, name, required)
85
82
  end
86
83
  alias :merge_var_add :create_tag
87
84
 
85
+ # Add a new Webhook URL for the given list
86
+ #
87
+ # Parameters:
88
+ # * list_id (String) = The mailing list ID value.
89
+ # * url (String) = A valid URL for the Webhook - it will be validated.
90
+ # * actions (Hash) = A hash of actions to fire this Webhook for including:
91
+ # * :subscribe (Boolean) - defaults to true.
92
+ # * :unsubscribe (Boolean) - defaults to true.
93
+ # * :profile (Boolean) - defaults to true.
94
+ # * :cleaned (Boolean) - defaults to true.
95
+ # * :upemail (Boolean) - defaults to true.
96
+ # * sources (Hash) = A hash of sources to fire this Webhook for including:
97
+ # * :user (Boolean) - defaults to true.
98
+ # * :admin (Boolean) - defaults to true.
99
+ # * :api (Boolean) - defaults to false.
100
+ #
101
+ # See the Mailchimp API documentation for more information.
102
+ #
103
+ # Returns:
104
+ # True if successful, error code if not.
105
+ #
88
106
  def create_webhook(list_id, url, actions = {}, sources = {})
89
- # Add a new Webhook URL for the given list
90
- #
91
- # Parameters:
92
- # list_id (String) = The mailing list ID value.
93
- # url (String) = A valid URL for the Webhook - it will be validated.
94
- # actions (Hash) = A hash of actions to fire this Webhook for including:
95
- # :subscribe (Boolean) - defaults to true.
96
- # :unsubscribe (Boolean) - defaults to true.
97
- # :profile (Boolean) - defaults to true.
98
- # :cleaned (Boolean) - defaults to true.
99
- # :upemail (Boolean) - defaults to true.
100
- # sources (Hash) = A hash of sources to fire this Webhook for including:
101
- # :user (Boolean) - defaults to true.
102
- # :admin (Boolean) - defaults to true.
103
- # :api (Boolean) - defaults to false.
104
- #
105
- # See the Mailchimp API documentation for more information.
106
- #
107
- # Returns:
108
- # True if successful, error code if not.
109
- #
110
107
  call("listWebhookAdd", list_id, url, actions, sources)
111
108
  end
112
109
  alias :webhook_add :create_webhook
113
110
 
111
+ # Delete a single Interest Group - if the last group for a list
112
+ # is deleted, this will also turn groups for the list off.
113
+ #
114
+ # Parameters:
115
+ # * list_id (String) = The mailing list ID value.
116
+ # * group (String) = The interest group to delete.
117
+ #
118
+ # Returns:
119
+ # True if successful, error code if not.
120
+ #
114
121
  def delete_group(list_id, group)
115
- # Delete a single Interest Group - if the last group for a list
116
- #is deleted, this will also turn groups for the list off.
117
- #
118
- # Parameters:
119
- # list_id (String) = The mailing list ID value.
120
- # group (String) = The interest group to delete.
121
- #
122
- # Returns:
123
- # True if successful, error code if not.
124
- #
125
122
  call("listInterestGroupDel", list_id, group)
126
123
  end
127
124
  alias :interest_group_del :delete_group
128
125
 
126
+ # Delete a merge tag from a given list and all its members.
127
+ # Seriously - the data is removed from all members as well!
128
+ # Note that on large lists this method may seem a bit slower
129
+ # than calls you typically make.
130
+ #
131
+ # Parameters:
132
+ # * list_id (String) = The mailing list ID value.
133
+ # * tag (String) = The merge tag to delete.
134
+ #
135
+ # Returns:
136
+ # True if successful, error code if not.
137
+ #
129
138
  def delete_tag(list_id, tag)
130
- # Delete a merge tag from a given list and all its members.
131
- # Seriously - the data is removed from all members as well!
132
- # Note that on large lists this method may seem a bit slower
133
- # than calls you typically make.
134
- #
135
- # Parameters:
136
- # list_id (String) = The mailing list ID value.
137
- # tag (String) = The merge tag to delete.
138
- #
139
- # Returns:
140
- # True if successful, error code if not.
141
- #
142
139
  call("listMergeVarDel", list_id, tag)
143
140
  end
144
141
  alias :merge_var_del :delete_tag
145
142
 
143
+ # Delete an existing Webhook URL from a given list.
144
+ #
145
+ # Parameters:
146
+ # * list_id (String) = The mailing list ID value.
147
+ # * url (String) = The URL of a Webhook on this list.
148
+ #
149
+ # Returns:
150
+ # True if successful, error code if not.
151
+ #
146
152
  def delete_webhook(list_id, url)
147
- # Delete an existing Webhook URL from a given list.
148
- #
149
- # Parameters:
150
- # list_id (String) = The mailing list ID value.
151
- # url (String) = The URL of a Webhook on this list.
152
- #
153
- # Returns:
154
- # True if successful, error code if not.
155
- #
156
153
  call("listWebhookDel", list_id, url)
157
154
  end
158
155
  alias :webhook_del :delete_webhook
159
156
 
157
+ # Get the list of interest groups for a given list, including
158
+ # the label and form information.
159
+ #
160
+ # Parameters:
161
+ # * list_id (String) = The mailing list ID value.
162
+ #
163
+ # Returns:
164
+ # A struct of interest groups for this list:
165
+ # * name (String) = Name for the Interest group.
166
+ # * form_field (String) = Gives the type of interest group: checkbox, radio, select, etc.
167
+ # * groups (Array) = Array of the group names
168
+ #
160
169
  def groups(list_id)
161
- # Get the list of interest groups for a given list, including
162
- # the label and form information.
163
- #
164
- # Parameters:
165
- # list_id (String) = The mailing list ID value.
166
- #
167
- # Returns:
168
- # A struct of interest groups for this list:
169
- # name (String) = Name for the Interest group.
170
- # form_field (String) = Gives the type of interest group: checkbox, radio, select, etc.
171
- # groups (Array) = Array of the group names
172
- #
173
170
  call("listInterestGroups", list_id)
174
171
  end
175
172
  alias :interest_groups :groups
176
173
 
174
+ # Access the Growth History by Month for a given list.
175
+ #
176
+ # Parameters:
177
+ # * list_id (String) = The mailing list ID value.
178
+ # * group (String) = The interest group to delete.
179
+ #
180
+ # Returns:
181
+ # An array of months and growth with the following fields:
182
+ # * month (String) = The Year and Month in question using YYYY-MM format.
183
+ # * existing (Integer) = Number of existing subscribers to start the month.
184
+ # * imports (Integer) = Number of subscribers imported during the month.
185
+ # * optins (Integer) = Number of subscribers who opted-in during the month.
186
+ #
177
187
  def growth_history(list_id)
178
- # Access the Growth History by Month for a given list.
179
- #
180
- # Parameters:
181
- # list_id (String) = The mailing list ID value.
182
- # group (String) = The interest group to delete.
183
- #
184
- # Returns:
185
- # An array of months and growth with the following fields:
186
- # month (String) = The Year and Month in question using YYYY-MM format.
187
- # existing (Integer) = Number of existing subscribers to start the month.
188
- # imports (Integer) = Number of subscribers imported during the month.
189
- # optins (Integer) = Number of subscribers who opted-in during the month.
190
- #
191
188
  call("listGrowthHistory", list_id)
192
189
  end
193
190
 
191
+ # Get all the information for a particular member of a list.
192
+ #
193
+ # Parameters:
194
+ # * list_id (String) = The mailing list ID value.
195
+ # * email (String) = the member email address to get information for OR the "id" for the member returned from listMemberInfo, Webhooks, and Campaigns
196
+ #
197
+ # Returns:
198
+ # An array of list member info with the following fields:
199
+ # * id (String) = The unique id for this email address on an account.
200
+ # * email (String) = The email address associated with this record.
201
+ # * email_type (String) = The type of emails this customer asked to get: html, text, or mobile.
202
+ # * merges (Array) = An associative array of all the merge tags and the data for those tags for this email address. Note: Interest Groups are returned as comma delimited strings - if a group name contains a comma, it will be escaped with a backslash. ie, "," => "\,"
203
+ # * status (String) = The subscription status for this email address, either subscribed, unsubscribed or cleaned.
204
+ # * ip_opt (String) = IP Address this address opted in from.
205
+ # * ip_signup (String) = IP Address this address signed up from.
206
+ # * campaign_id (String) = If the user is unsubscribed and they unsubscribed from a specific campaign, that campaign_id will be listed, otherwise this is not returned.
207
+ # * list (Array) = An associative array of the other lists this member belongs to - the key is the list id and the value is their status in that list.
208
+ # * timestamp (Date) = The time this email address was added to the list
209
+ #
194
210
  def member_info(list_id, email)
195
- # Get all the information for a particular member of a list.
196
- #
197
- # Parameters:
198
- # list_id (String) = The mailing list ID value.
199
- # email (String) = the member email address to get information for
200
- # OR the "id" for the member returned from listMemberInfo,
201
- # Webhooks, and Campaigns
202
- #
203
- # Returns:
204
- # An array of list member info with the following fields:
205
- # id (String) = The unique id for this email address on an account.
206
- # email (String) = The email address associated with this record.
207
- # email_type (String) = The type of emails this customer asked to get: html, text, or mobile.
208
- # merges (Array) = An associative array of all the merge tags and the data for those tags
209
- # for this email address. Note: Interest Groups are returned as comma
210
- # delimited strings - if a group name contains a comma, it will be escaped
211
- # with a backslash. ie, "," => "\,"
212
- # status (String) = The subscription status for this email address, either subscribed,
213
- # unsubscribed or cleaned.
214
- # ip_opt (String) = IP Address this address opted in from.
215
- # ip_signup (String) = IP Address this address signed up from.
216
- # campaign_id (String) = If the user is unsubscribed and they unsubscribed from a specific campaign,
217
- # that campaign_id will be listed, otherwise this is not returned.
218
- # list (Array) = An associative array of the other lists this member belongs to - the key is
219
- # the list id and the value is their status in that list.
220
- # timestamp (Date) = The time this email address was added to the list
221
- #
222
211
  call("listMemberInfo", list_id, email)
223
212
  end
224
213
 
214
+ # Get all of the list members for a list that are of a particular status.
215
+ #
216
+ # Parameters:
217
+ # * list_id (String) = The mailing list ID value.
218
+ # * status (String) = One of subscribed, unsubscribed, cleaned, updated.
219
+ # * since (Datetime) = Pull all members whose status (subscribed/unsubscribed/cleaned) has changed or whose profile (updated) has changed since this date/time (in GMT).
220
+ # * start (Integer) = The page number to start at - defaults to 0.
221
+ # * limit (integer) = The number of results to return - defaults to 100, upper limit set at 15000.
222
+ #
223
+ # Returns:
224
+ # An array of list member structs:
225
+ # * email (String) = Member email address.
226
+ # * timestamp (DateTime) = timestamp of their associated status date in GMT.
227
+ #
225
228
  def members(list_id, status = "subscribed", since = "2000-01-01 00:00:00", start = 0, limit = 100)
226
- # Get all of the list members for a list that are of a particular status.
227
- #
228
- # Parameters:
229
- # list_id (String) = The mailing list ID value.
230
- # status (String) = One of subscribed, unsubscribed, cleaned, updated.
231
- # since (Datetime) = Pull all members whose status (subscribed/unsubscribed/cleaned) has changed or whose
232
- # profile (updated) has changed since this date/time (in GMT).
233
- # start (Integer) = The page number to start at - defaults to 0.
234
- # limit (integer) = The number of results to return - defaults to 100, upper limit set at 15000.
235
- #
236
- # Returns:
237
- # An array of list member structs:
238
- # email (String) = Member email address.
239
- # timestamp (DateTime) = timestamp of their associated status date in GMT.
240
- #
241
229
  call("listMembers", list_id, status, since, start, limit)
242
230
  end
243
231
 
232
+ # Get the list of merge tags for a given list, including their name, tag, and required setting.
233
+ #
234
+ # Parameters:
235
+ # * list_id (String) = The mailing list ID value.
236
+ #
237
+ # Returns:
238
+ # An array of merge tags for this list:
239
+ # * name (String) = Name of the merge field.
240
+ # * req (Char) = Denotes whether the field is required (Y) or not (N).
241
+ # * tag (String) = The merge tag.
244
242
  def merge_tags(list_id)
245
- # Get the list of merge tags for a given list, including their name, tag, and required setting.
246
- #
247
- # Parameters:
248
- # list_id (String) = The mailing list ID value.
249
- #
250
- # Returns:
251
- # An array of merge tags for this list:
252
- # name (String) = Name of the merge field.
253
- # req (Char) = Denotes whether the field is required (Y) or not (N).
254
- # tag (String) = The merge tag.
255
243
  call("listMergeVars", list_id)
256
244
  end
257
245
  alias :merge_vars :merge_tags
258
246
 
247
+ # Allows one to test their segmentation rules before creating a campaign using them.
248
+ #
249
+ # Parameters:
250
+ # * list_id (String) = The mailing list ID value.
251
+ # * options (Hash) = Please refer to the Mailchimp API documentation for more information.
252
+ #
253
+ # Returns:
254
+ #
255
+ #
259
256
  def segment_test(list_id, options = {})
260
- # Allows one to test their segmentation rules before creating a campaign using them.
261
- #
262
- # Parameters:
263
- # list_id (String) = The mailing list ID value.
264
- # options (Hash) = Please refer to the Mailchimp API documentation for more information.
265
- #
266
- # Returns:
267
- #
268
- #
269
257
  call("campaignSegmentTest", list_id, options)
270
258
  end
271
259
 
260
+ # Subscribe the provided email to a list.
261
+ #
262
+ # Parameters:
263
+ # * list_id (String) = The mailing list ID value.
264
+ # * email (String) = The email address to subscribe.
265
+ # * merge_vars (Hash) = A hash of the merge tags that you want to include.
266
+ #
267
+ # Returns:
268
+ # True on success, false on failure.
269
+ #
272
270
  def subscribe(list_id, email, merge_vars = {}, options = {})
273
- # Subscribe the provided email to a list.
274
- #
275
- # Parameters:
276
- # list_id (String) = The mailing list ID value.
277
- # email (String) = The email address to subscribe.
278
- # merge_vars (Hash) = A hash of the merge tags that you want to include.
279
- #
280
- # Returns:
281
- # True on success, false on failure.
282
- #
283
271
  merge_tags = clean_merge_tags merge_vars
284
272
  options = apply_defaults_to({:email_type => "html"}.merge(options))
285
273
  call(
@@ -297,106 +285,104 @@ module Hominid
297
285
  )
298
286
  end
299
287
 
288
+ # Subscribe a batch of email addresses to a list at once.
289
+ #
290
+ # Parameters:
291
+ # * list_id (String) = The mailing list ID value.
292
+ # * subscribers (Array) = An array of email addresses to subscribe.
293
+ # * merge_vars (Hash) = A hash of subscription options. See the Mailchimp API documentation.
294
+ #
295
+ # Returns:
296
+ # An array of result counts and errors:
297
+ # * success_count (Integer) = Number of email addresses that were succesfully added/updated.
298
+ # * error_count (Integer) = Number of email addresses that failed during addition/updating.
299
+ # * errors (Array) = Array of error structs. Each error struct will contain "code", "message", and the full struct that failed.
300
+ #
300
301
  def subscribe_many(list_id, subscribers, options = {})
301
- # Subscribe a batch of email addresses to a list at once.
302
- #
303
- # Parameters:
304
- # list_id (String) = The mailing list ID value.
305
- # subscribers (Array) = An array of email addresses to subscribe.
306
- # merge_vars (Hash) = A hash of subscription options. See the Mailchimp API documentation.
307
- #
308
- # Returns:
309
- # An array of result counts and errors:
310
- # success_count (Integer) = Number of email addresses that were succesfully added/updated.
311
- # error_count (Integer) = Number of email addresses that failed during addition/updating.
312
- # errors (Array) = Array of error structs. Each error struct will contain "code",
313
- # "message", and the full struct that failed.
314
- #
315
302
  subscribers = subscribers.collect { |subscriber| clean_merge_tags(subscriber) }
316
303
  options = apply_defaults_to({:update_existing => true}.merge(options))
317
304
  call("listBatchSubscribe", list_id, subscribers, *options.values_at(:double_opt_in, :update_existing, :replace_interests))
318
305
  end
319
306
  alias :batch_subscribe :subscribe_many
320
307
 
308
+ # Unsubscribe the given email address from the list.
309
+ #
310
+ # Parameters:
311
+ # * list_id (String) = The mailing list ID value.
312
+ # * current_email (String) = The email address to unsubscribe OR the email "id".
313
+ # * options (Hash) = A hash of unsubscribe options including:
314
+ # * :delete_member (defaults to false)
315
+ # * :send_goodbye (defaults to false)
316
+ # * :send_notify (defaults to false).
317
+ #
318
+ # Returns:
319
+ # True on success, false on failure
320
+ #
321
321
  def unsubscribe(list_id, current_email, options = {})
322
- # Unsubscribe the given email address from the list.
323
- #
324
- # Parameters:
325
- # list_id (String) = The mailing list ID value.
326
- # current_email (String) = The email address to unsubscribe OR the email "id".
327
- # options (Hash) = A hash of unsubscribe options including:
328
- # :delete_member (defaults to false)
329
- # :send_goodbye (defaults to false)
330
- # :send_notify (defaults to false).
331
- #
332
- # Returns:
333
- # True on success, false on failure
334
- #
335
322
  options = apply_defaults_to({:delete_member => true}.merge(options))
336
323
  call("listUnsubscribe", list_id, current_email, *options.values_at(:delete_member, :send_goodbye, :send_notify))
337
324
  end
338
325
 
326
+ # Unsubscribe a batch of email addresses to a list.
327
+ #
328
+ # Parameters:
329
+ # * list_id (String) = The mailing list ID value.
330
+ # * emails (Array) = An array of email addresses to unsubscribe.
331
+ # * options (Hash) = A hash of unsubscribe options including:
332
+ # * :delete_member (defaults to false)
333
+ # * :send_goodbye (defaults to false)
334
+ # * :send_notify (defaults to false)
335
+ #
336
+ # Returns:
337
+ #
339
338
  def unsubscribe_many(list_id, emails, options = {})
340
- # Unsubscribe a batch of email addresses to a list.
341
- #
342
- # Parameters:
343
- # list_id (String) = The mailing list ID value.
344
- # emails (Array) = An array of email addresses to unsubscribe.
345
- # options (Hash) = A hash of unsubscribe options including:
346
- # :delete_member (defaults to false)
347
- # :send_goodbye (defaults to false)
348
- # :send_notify (defaults to false)
349
- #
350
- # Returns:
351
- #
352
339
  options = apply_defaults_to({:delete_member => true}.merge(options))
353
340
  call("listBatchUnsubscribe", list_id, emails, *options.values_at(:delete_member, :send_goodbye, :send_notify))
354
341
  end
355
342
  alias :batch_unsubscribe :unsubscribe_many
356
343
 
344
+ # Change the name of an Interest Group.
345
+ #
346
+ # Parameters:
347
+ # * list_id (String) = The mailing list ID value.
348
+ # * old_name (String) = The interest group name to be changed.
349
+ # * new_name (String) = The new interest group name to be set.
350
+ #
351
+ # Returns:
352
+ # True if successful, error code if not.
353
+ #
357
354
  def update_group(list_id, old_name, new_name)
358
- # Change the name of an Interest Group.
359
- #
360
- # Parameters:
361
- # list_id (String) = The mailing list ID value.
362
- # old_name (String) = The interest group name to be changed.
363
- # new_name (String) = The new interest group name to be set.
364
- #
365
- # Returns:
366
- # True if successful, error code if not.
367
- #
368
355
  call("listInterestGroupUpdate", list_id, old_name, new_name)
369
356
  end
370
357
 
358
+ # Edit the email address, merge fields, and interest groups for a list member.
359
+ #
360
+ # Parameters:
361
+ # * list_id (String) = The mailing list ID value.
362
+ # * email (String) = The current email address of the member to update OR the "id" for the member.
363
+ # * merge_tags (Hash) = Hash of new field values to update the member with. Ex: {FNAME => 'Bob', :LNAME => 'Smith'}
364
+ # * email_type (String) = One of 'html', 'text', or 'mobile'.
365
+ # * replace_interests (Boolean) = Whether or not to replace the interest groups with the updated groups provided.
366
+ #
367
+ # Returns:
368
+ # True on success, false on failure
369
+ #
371
370
  def update_member(list_id, email, merge_tags = {}, email_type = "html", replace_interests = true)
372
- # Edit the email address, merge fields, and interest groups for a list member.
373
- #
374
- # Parameters:
375
- # list_id (String) = The mailing list ID value.
376
- # email (String) = The current email address of the member to update OR the "id" for the member.
377
- # merge_tags (Hash) = Hash of new field values to update the member with.
378
- # Ex: {FNAME => 'Bob', :LNAME => 'Smith'}
379
- # email_type (String) = One of 'html', 'text', or 'mobile'.
380
- # replace_interests (Boolean) = Whether or not to replace the interest groups with the updated groups provided.
381
- #
382
- # Returns:
383
- # True on success, false on failure
384
- #
385
371
  call("listUpdateMember", list_id, email, merge_tags, email_type, replace_interests)
386
372
  end
387
373
 
374
+ # Return the Webhooks configured for the given list.
375
+ #
376
+ # Parameters:
377
+ # * list_id (String) = The mailing list ID value.
378
+ #
379
+ # Returns:
380
+ # An array of webhooks for this list including:
381
+ # * url (String) = The URL for this Webhook.
382
+ # * action (Array) = The possible actions and whether they are enabled.
383
+ # * sources (Array) = The possible sources and whether they are enabled.
384
+ #
388
385
  def webhooks(list_id)
389
- # Return the Webhooks configured for the given list.
390
- #
391
- # Parameters:
392
- # list_id (String) = The mailing list ID value.
393
- #
394
- # Returns:
395
- # An array of webhooks for this list including:
396
- # url (String) = The URL for this Webhook.
397
- # action (Array) = The possible actions and whether they are enabled.
398
- # sources (Array) = The possible sources and whether they are enabled.
399
- #
400
386
  call("listWebhooks", list_id)
401
387
  end
402
388