1 <?php
2 namespace MailChimp\Lists;
3
4 use MailChimp\MailChimp as MailChimp;
5 use MailChimp\Lists\Interests as Interests;
6 use MailChimp\Lists\Members as Members;
7 use MailChimp\Lists\MergeFields as MergeFields;
8 use MailChimp\Lists\Segments as Segments;
9 use MailChimp\Lists\SignupForms as SignupForms;
10 use MailChimp\Lists\Webhooks as Webhooks;
11
12 class Lists extends MailChimp
13 {
14 /**
15 * Get a list of lists for the account
16 *
17 * Available query fields:
18 * array["fields"] array list of strings of response fields to return
19 * array["exclude_fields"] array list of strings of response fields to exclude (not to be used with "fields")
20 * array["count"] int number of records to return
21 * array["offset"] int number of records from a collection to skip.
22 * array["before_date_created"] string Restrict response to lists created before the set date.
23 * ISO 8601 time format: 2015-10-21T15:41:36+00:00.
24 * array["since_date_created"] string Restrict results to lists created after the set date.
25 * ISO 8601 time format: 2015-10-21T15:41:36+00:00.
26 * array["before_campaign_last_sent"] string Restrict results to lists created before the last campaign send date.
27 * ISO 8601 time format: 2015-10-21T15:41:36+00:00.
28 * array["since_campaign_last_sent"] string Restrict results to lists created after the last campaign send date.
29 * ISO 8601 time format: 2015-10-21T15:41:36+00:00.
30 * email string Restrict results to lists that include a specific subscriber’s email address.`
31 *
32 * @param array $query (See Above) OPTIONAL associative array of query parameters.
33 * @return object
34 */
35 public function getLists(array $query = [])
36 {
37 return self::execute("GET", "lists", $query);
38 }
39
40 /**
41 * Get a single list
42 *
43 * array["fields"] array list of strings of response fields to return
44 * array["exclude_fields"] array list of strings of response fields to exclude (not to be used with "fields")
45 *
46 * @param string $list_id for the list instance
47 * @param array $query (See Above) OPTIONAL associative array of query parameters.
48 * @return object list instance
49 */
50 public function getList($list_id, array $query = [])
51 {
52 return self::execute("GET", "lists/{$list_id}", $query);
53 }
54
55 /**
56 * Create a list
57 *
58 * ["name"] string required
59 * ["permission_reminder"] string required
60 * ["email_type_option"] boolean required
61 * array["contact"] array required
62 * ["company"] string required
63 * ["address1"] string required
64 * ["address2"] string
65 * ["city"] string required
66 * ["state"] string required
67 * ["zip"] string required
68 * ["country"] string required
69 * ["phone"] string
70 * array["campaign_defaults"] array required
71 * ["from_name"] string required
72 * ["from_email"] string required
73 * ["subject"] string required
74 * ["language"] string required
75 * array["optional_settings"]
76 * ["use_archive_bar"] boolean
77 * ["notify_on_subscribe"] string The email address to send subscribe notifications to.
78 * ["notify_on_unsubscribe"] string The email address to send unsubscribe notifications to.
79 * ["visibility"] string Whether this list is public or private.
80 * Possible Values: pub,prv
81 * @param string $name
82 * @param string $permission_reminder
83 * @param boolean $email_type_option
84 * @param array $campaign_defaults
85 * @param array $contact
86 * @param array $optional_setttings (See Above)
87 * @return object created list information
88 */
89 public function createList($name, $permission_reminder, $email_type_option, array $campaign_defaults = [], array $contact = [], array $optional_settings = null)
90 {
91 $optional_fields = ["visibility", "notify_on_subscribe", "notify_on_unsubscribe", "use_archive_bar"];
92 $data = [
93 "name" => $name,
94 "permission_reminder" => $permission_reminder,
95 "email_type_option" => $email_type_option,
96 "campaign_defaults" => $campaign_defaults,
97 "contact" => $contact
98 ];
99
100 // If the optional fields are passed, process them against the list of optional fields.
101 if (isset($optional_settings)) {
102 $data = array_merge($data, self::optionalFields($optional_fields, $optional_settings));
103 }
104
105 return self::execute("POST", "lists", $data);
106 }
107
108 /**
109 * Update an existing list
110 *
111 * @param string $list_id list id for list to edit
112 * @param array $data fields to update (See structure from createList)
113 * @return object updated list
114 */
115 public function updateList($list_id, array $data = [])
116 {
117 return self::execute("PATCH", "lists/{$list_id}", $data);
118 }
119
120 /*
121 * Batch Sub/Unsub members
122 */
123 public function batchMembers($list_id, array $batch = [], $updateExisting = false)
124 {
125
126 $b = ["members" => $batch, "update_existing" => $updateExisting];
127 return self::execute("POST", "lists/{$list_id}", $b);
128 }
129
130 /**
131 * Get all abuse reports for a specific list.
132 *
133 * Available query fields:
134 * array["fields"] array list of strings of response fields to return
135 * array["exclude_fields"] array list of strings of response fields to exclude (not to be used with "fields")
136 * array["count"] int number of records to return
137 * array["offset"] int number of records from a collection to skip.
138 * @param string $list_id list id for list to edit
139 * @param array $query fields to update (See structure from createList)
140 * @return object
141 */
142 public function getAbuseReports($list_id, array $query = [])
143 {
144 return self::execute("GET", "lists/{$list_id}/abuse-reports", $query);
145 }
146
147 /**
148 * Get details about a specific abuse report.
149 *
150 * Available query fields:
151 * array["fields"] array list of strings of response fields to return
152 * array["exclude_fields"] array list of strings of response fields to exclude (not to be used with "fields")
153 * @param string $list_id list id for list to edit
154 * @param string $reportId
155 * @param array $query fields to update (See structure from createList)
156 * @return object
157 */
158 public function getAbuseReport($list_id, $report_id, array $query = [])
159 {
160 return self::execute("GET", "lists/{$list_id}/abuse-reports/{$report_id}", $query);
161 }
162
163 /**
164 * Get recent daily, aggregated activity stats for your list.
165 *
166 * For example, view unsubscribes, signups, total emails sent, opens, clicks, and more, for up to 180 days.
167 *
168 * Available query fields:
169 * array["fields"] array list of strings of response fields to return
170 * array["exclude_fields"] array list of strings of response fields to exclude (not to be used with "fields")
171 * @param string $list_id list id for list to edit
172 * @param array $query fields to update (See structure from createList)
173 * @return object
174 */
175 public function getActivity($list_id, array $query = [])
176 {
177 return self::execute("GET", "lists/{$list_id}/activity", $query);
178 }
179
180 /**
181 * Get a list of the top email clients based on user-agent strings.
182 *
183 * Available query fields:
184 * array["fields"] array list of strings of response fields to return
185 * array["exclude_fields"] array list of strings of response fields to exclude (not to be used with "fields")
186 * @param string $list_id list id for list to edit
187 * @param array $query fields to update (See structure from createList)
188 * @return object
189 */
190 public function getClients($list_id, array $query = [])
191 {
192 return self::execute("GET", "lists/{$list_id}/clients", $query);
193 }
194
195 /**
196 * Get a month-by-month summary of a specific list’s growth activity.
197 *
198 * Available query fields:
199 * array["fields"] array list of strings of response fields to return
200 * array["exclude_fields"] array list of strings of response fields to exclude (not to be used with "fields")
201 * array["count"] int number of records to return
202 * array["offset"] int number of records from a collection to skip.
203 * @param string $list_id list id for list to edit
204 * @param array $query fields to update (See structure from createList)
205 * @return object
206 */
207 public function getGrowthHistory($list_id, array $query = [])
208 {
209 return self::execute("GET", "lists/{$list_id}/growth-history", $query);
210 }
211
212 /**
213 * Get a summary of a specific list’s growth activity for a specific month and year.
214 *
215 * Available query fields:
216 * array["fields"] array list of strings of response fields to return
217 * array["exclude_fields"] array list of strings of response fields to exclude (not to be used with "fields")
218 * @param string $list_id list id for list to edit
219 * @param string $month format: yyyy-mm
220 * @param array $query fields to update (See structure from createList)
221 * @return object
222 */
223 public function getGrowthHistoryMonth($list_id, $month, array $query = [])
224 {
225 return self::execute("GET", "lists/{$list_id}/growth-history/{$month}", $query);
226 }
227
228
229
230 /**
231 * Delete a list
232 *
233 * @param string list id
234 */
235 public function deleteList($list_id)
236 {
237 return self::execute("DELETE", "lists/{$list_id}");
238 }
239
240
241 /**
242 * Instantiate lists subresources
243 */
244
245 /**
246 * Instantiate lists interests subresources
247 */
248 public function interests()
249 {
250 return new Interests;
251 }
252
253 /**
254 * Instantiate lists Members subresources
255 */
256 public function members()
257 {
258 return new Members;
259 }
260
261 /**
262 * Instantiate lists MergeFields subresources
263 */
264 public function mergeFields()
265 {
266 return new MergeFields;
267 }
268
269 /**
270 * Instantiate lists Segments subresources
271 */
272 public function segments()
273 {
274 return new Segments;
275 }
276
277 /**
278 * Instantiate lists signupForms subresources
279 */
280 public function signupForms()
281 {
282 return new signupForms;
283 }
284
285 /**
286 * Instantiate lists webhooks subresources
287 */
288 public function webhooks()
289 {
290 return new Webhooks;
291 }
292
293 }
294