├── forms
├── index.php
└── settings.php
├── handlers
├── api.php
├── subscribe_widget.php
├── admin.php
├── index.php
└── settings.php
├── conf
├── config.php
└── embed.php
├── elefant.json
├── composer.json
├── lib
├── API.php
├── Functions.php
└── MCAPI.php
├── views
├── index.html
├── subscribe_widget.html
├── admin.html
└── settings.html
└── README.md
/forms/index.php:
--------------------------------------------------------------------------------
1 | ;
--------------------------------------------------------------------------------
/handlers/api.php:
--------------------------------------------------------------------------------
1 | restful (new newsletter\API);
4 |
5 | ?>
--------------------------------------------------------------------------------
/forms/settings.php:
--------------------------------------------------------------------------------
1 | ;
--------------------------------------------------------------------------------
/handlers/subscribe_widget.php:
--------------------------------------------------------------------------------
1 | render (
4 | 'newsletter/subscribe_widget',
5 | array (
6 | 'list_id' => $data['list'],
7 | 'fwd' => $data['fwd'],
8 | 'rand' => mt_rand ()
9 | )
10 | );
11 |
12 | ?>
--------------------------------------------------------------------------------
/conf/config.php:
--------------------------------------------------------------------------------
1 | ;
--------------------------------------------------------------------------------
/conf/embed.php:
--------------------------------------------------------------------------------
1 | ;
--------------------------------------------------------------------------------
/elefant.json:
--------------------------------------------------------------------------------
1 | {
2 | "type": "app",
3 | "folder": "newsletter",
4 | "name": "Newsletter",
5 | "version": "0.9.0",
6 | "website": "http://www.elefantcms.com/",
7 | "repository": "git://github.com/shortjared/newsletter.git",
8 | "author": {
9 | "name": "Jared Short",
10 | "email": "jaredlshort@gmail.com"
11 | },
12 | "requires": {
13 | "php": "5.3.2",
14 | "elefant": "1.0.1"
15 | }
16 | }
17 |
--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "elefant/app-newsletter",
3 | "type": "elefant-app",
4 | "description": "Newsletter via Mailchimp app for the Elefant CMS",
5 | "keywords": ["newsletter", "mailchimp", "subscribe", "cms", "app"],
6 | "license": "MIT",
7 | "authors": [
8 | {
9 | "name": "Jared Short",
10 | "email": "jaredlshort@gmail.com",
11 | "homepage": "http://www.jaredshort.com/"
12 | }
13 | ],
14 | "repositories": [
15 | {"type": "git", "url": "http://github.com/jbroadway/elefant_installer"}
16 | ],
17 | "require": {
18 | "elefant/app-installer": "*"
19 | }
20 | }
21 |
--------------------------------------------------------------------------------
/lib/API.php:
--------------------------------------------------------------------------------
1 | listSubscribe (
11 | $_POST['list_id'],
12 | $_POST['email']
13 | );
14 |
15 | if ($api->errorCode == 214) {
16 | return $this->error (__ ('It looks like you\'re already subscribed. Thank you!'));
17 | } elseif ($api->errorCode) {
18 | return $this->error (__ ('Unable to subscribe. Please try again later.'));
19 | }
20 |
21 | return __ ('Thank you for subscribing. Check your inbox for an email to confirm your subscription.');
22 | }
23 | }
24 |
25 | ?>
--------------------------------------------------------------------------------
/lib/Functions.php:
--------------------------------------------------------------------------------
1 | 0,
12 | 'value' => "-- Please Select List --"
13 | );
14 |
15 | foreach ($lists as $list) {
16 | $retarr[] = (object) array (
17 | 'key' => $list['id'],
18 | 'value' => $list['name']
19 | );
20 | }
21 |
22 | return $retarr;
23 | }
24 |
25 | /**
26 | * Return a raw array of list results.
27 | */
28 | function newsletter_raw_lists ($apikey = null) {
29 | $apikey = $apikey ? $apikey : Appconf::newsletter ('Newsletter', 'mailchimp_api');
30 | $api = new MCAPI($apikey);
31 | $retval = $api->lists ();
32 | return is_array ($retval['data']) ? $retval['data'] : array ();
33 | }
34 |
35 | ?>
--------------------------------------------------------------------------------
/views/index.html:
--------------------------------------------------------------------------------
1 |
26 |
--------------------------------------------------------------------------------
/handlers/admin.php:
--------------------------------------------------------------------------------
1 | require_admin ();
9 |
10 | $page->title = 'Newsletters';
11 | $page->layout = 'admin';
12 |
13 | if (! file_exists ('conf/app.newsletter.' . ELEFANT_ENV . '.php')) {
14 | $this->redirect ('/newsletter/settings');
15 | }
16 |
17 | $apikey = Appconf::newsletter ('Newsletter', 'mailchimp_api');
18 | $api = new MCAPI($apikey);
19 |
20 | $retval = $api->lists();
21 |
22 | if ($api->errorCode) {
23 | printf ('%s
', __ ('Unable to load lists from MailChimp at this time.'));
24 | error_log ('[newsletter/admin] ' . $api->errorCode . ' ' . $api->errorMessage);
25 | } else {
26 | echo $tpl->render ('newsletter/admin', array (
27 | 'lists_count' => $retval['total'],
28 | 'lists' => $retval['data'],
29 | 'default_list' => Appconf::newsletter ('Newsletter', 'default_list')
30 | ));
31 | }
32 |
33 | ?>
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | This is an incredibly easy mailchimp integration for a newsletter subscription form/widget.
2 |
3 | ### Installation
4 |
5 | To install, unzip it into your apps folder.(Or install through git routine).
6 |
7 | Visit the link "Newsletter" in your admin tools, on the first time you will be asked for your mailchimp API key. That's it, you're done with installation.
8 |
9 |
10 | ### Using Newsletter Widget
11 | You can use it in any page, or block element. Simply click the "Newsletter : Subscription Widget" and select the mailing list you wish the individual to subscribe to.
12 |
13 | You can have as many widgets on your site, and even an single page as you want.
14 |
15 |
16 | ### Admin Page
17 |
18 | This is a quick view some of the major stats about your mailing campaigns.
19 |
20 |
21 | ### Support and Updates
22 |
23 | There is no official support or updates planned. You can seek help at http://www.elefantcms.com/forum. I will be working on this as I see fit. If you submit a pull request I will review it.
24 |
25 |
26 |
--------------------------------------------------------------------------------
/views/subscribe_widget.html:
--------------------------------------------------------------------------------
1 |
6 |
7 |
40 |
--------------------------------------------------------------------------------
/handlers/index.php:
--------------------------------------------------------------------------------
1 | id = 'newsletter';
4 | $page->title = Appconf::newsletter ('Newsletter', 'title');
5 | $page->layout = Appconf::newsletter ('Newsletter', 'layout');
6 |
7 | $default_list = Appconf::newsletter ('Newsletter', 'default_list');
8 |
9 | if (empty ($default_list)) {
10 | printf ('%s
', __ ('The default newsletter has not yet been configured.'));
11 | return;
12 | }
13 |
14 | $form = new Form ('post', $this);
15 |
16 | echo $form->handle (function ($form) use ($default_list) {
17 | $apikey = Appconf::newsletter ('Newsletter', 'mailchimp_api');
18 | $api = new MCAPI ($apikey);
19 |
20 | $retval = $api->listSubscribe (
21 | $default_list,
22 | $_POST['email'],
23 | array (
24 | 'FNAME' => $_POST['first_name'],
25 | 'LNAME' => $_POST['last_name']
26 | )
27 | );
28 |
29 | if ($api->errorCode) {
30 | printf ('%s
', __ ('Unable to load lists from MailChimp at this time.'));
31 | error_log ('[newsletter/index] ' . $api->errorCode . ' ' . $api->errorMessage);
32 | return;
33 | }
34 |
35 | $fwd = Appconf::newsletter ('Newsletter', 'forward_on_success');
36 | if ($fwd != '') {
37 | $form->controller->redirect ($fwd);
38 | } else {
39 | printf ('%s
', __ ('Thank you for signing up to receive our newsletter. Check your inbox for an email to confirm your subscription.'));
40 | }
41 | });
42 |
43 | ?>
--------------------------------------------------------------------------------
/views/admin.html:
--------------------------------------------------------------------------------
1 |
2 | {"Settings"}
3 | |
4 | Visit MailChimp »
5 |
6 |
7 | {% foreach lists %}
8 |
9 |
{{ loop_value['name'] }}{% if loop_value['id'] == $data->default_list %} ({"default list"}){% end %}
10 |
11 |
12 | {{ loop_value['stats']['member_count'] }}
13 | {"Subscribers"}
14 |
15 |
16 |
17 | {{ loop_value['stats']['open_rate']|round (%s, 2) }}%
18 | {"Opens"}
19 |
20 |
21 |
22 | {{ loop_value['stats']['click_rate']|round (%s, 2) }}%
23 | {"Clicks"}
24 |
25 |
26 |
{"Subscribe link"}: {{ loop_value['subscribe_url_short'] }}
27 |
%s
',
47 | __ ('Unable to save changes. Check your permissions and try again.')
48 | );
49 | return;
50 | }
51 |
52 | $form->controller->add_notification (__ ('Settings saved.'));
53 | $form->controller->redirect ('/newsletter/admin');
54 | });
55 |
56 | ?>
--------------------------------------------------------------------------------
/lib/MCAPI.php:
--------------------------------------------------------------------------------
1 | secure = $secure;
41 | $this->apiUrl = parse_url("http://api.mailchimp.com/" . $this->version . "/?output=php");
42 | $this->api_key = $apikey;
43 | }
44 | function setTimeout($seconds){
45 | if (is_int($seconds)){
46 | $this->timeout = $seconds;
47 | return true;
48 | }
49 | }
50 | function getTimeout(){
51 | return $this->timeout;
52 | }
53 | function useSecure($val){
54 | if ($val===true){
55 | $this->secure = true;
56 | } else {
57 | $this->secure = false;
58 | }
59 | }
60 |
61 | /**
62 | * Unschedule a campaign that is scheduled to be sent in the future
63 | *
64 | * @section Campaign Related
65 | * @example mcapi_campaignUnschedule.php
66 | * @example xml-rpc_campaignUnschedule.php
67 | *
68 | * @param string $cid the id of the campaign to unschedule
69 | * @return boolean true on success
70 | */
71 | function campaignUnschedule($cid) {
72 | $params = array();
73 | $params["cid"] = $cid;
74 | return $this->callServer("campaignUnschedule", $params);
75 | }
76 |
77 | /**
78 | * Schedule a campaign to be sent in the future
79 | *
80 | * @section Campaign Related
81 | * @example mcapi_campaignSchedule.php
82 | * @example xml-rpc_campaignSchedule.php
83 | *
84 | * @param string $cid the id of the campaign to schedule
85 | * @param string $schedule_time the time to schedule the campaign. For A/B Split "schedule" campaigns, the time for Group A - in YYYY-MM-DD HH:II:SS format in GMT
86 | * @param string $schedule_time_b optional -the time to schedule Group B of an A/B Split "schedule" campaign - in YYYY-MM-DD HH:II:SS format in GMT
87 | * @return boolean true on success
88 | */
89 | function campaignSchedule($cid, $schedule_time, $schedule_time_b=NULL) {
90 | $params = array();
91 | $params["cid"] = $cid;
92 | $params["schedule_time"] = $schedule_time;
93 | $params["schedule_time_b"] = $schedule_time_b;
94 | return $this->callServer("campaignSchedule", $params);
95 | }
96 |
97 | /**
98 | * Resume sending an AutoResponder or RSS campaign
99 | *
100 | * @section Campaign Related
101 | *
102 | * @param string $cid the id of the campaign to pause
103 | * @return boolean true on success
104 | */
105 | function campaignResume($cid) {
106 | $params = array();
107 | $params["cid"] = $cid;
108 | return $this->callServer("campaignResume", $params);
109 | }
110 |
111 | /**
112 | * Pause an AutoResponder orRSS campaign from sending
113 | *
114 | * @section Campaign Related
115 | *
116 | * @param string $cid the id of the campaign to pause
117 | * @return boolean true on success
118 | */
119 | function campaignPause($cid) {
120 | $params = array();
121 | $params["cid"] = $cid;
122 | return $this->callServer("campaignPause", $params);
123 | }
124 |
125 | /**
126 | * Send a given campaign immediately. For RSS campaigns, this will "start" them.
127 | *
128 | * @section Campaign Related
129 | *
130 | * @example mcapi_campaignSendNow.php
131 | * @example xml-rpc_campaignSendNow.php
132 | *
133 | * @param string $cid the id of the campaign to send
134 | * @return boolean true on success
135 | */
136 | function campaignSendNow($cid) {
137 | $params = array();
138 | $params["cid"] = $cid;
139 | return $this->callServer("campaignSendNow", $params);
140 | }
141 |
142 | /**
143 | * Send a test of this campaign to the provided email address
144 | *
145 | * @section Campaign Related
146 | *
147 | * @example mcapi_campaignSendTest.php
148 | * @example xml-rpc_campaignSendTest.php
149 | *
150 | * @param string $cid the id of the campaign to test
151 | * @param array $test_emails an array of email address to receive the test message
152 | * @param string $send_type optional by default (null) both formats are sent - "html" or "text" send just that format
153 | * @return boolean true on success
154 | */
155 | function campaignSendTest($cid, $test_emails=array (
156 | ), $send_type=NULL) {
157 | $params = array();
158 | $params["cid"] = $cid;
159 | $params["test_emails"] = $test_emails;
160 | $params["send_type"] = $send_type;
161 | return $this->callServer("campaignSendTest", $params);
162 | }
163 |
164 | /**
165 | * Allows one to test their segmentation rules before creating a campaign using them
166 | *
167 | * @section Campaign Related
168 | * @example mcapi_campaignSegmentTest.php
169 | * @example xml-rpc_campaignSegmentTest.php
170 | *
171 | * @param string $list_id the list to test segmentation on - get lists using lists()
172 | * @param array $options with 2 keys:
173 | string "match" controls whether to use AND or OR when applying your options - expects "any" (for OR) or "all" (for AND)
174 | array "conditions" - up to 10 different criteria to apply while segmenting. Each criteria row must contain 3 keys - "field", "op", and "value" - and possibly a fourth, "extra", based on these definitions:
175 |
176 | Field = "date" : Select based on signup date
177 | Valid Op(eration): eq (is) / gt (after) / lt (before)
178 | Valid Values:
179 | string last_campaign_sent uses the date of the last campaign sent
180 | string campaign_id - uses the send date of the campaign that carriers the Id submitted - see campaigns()
181 | string YYYY-MM-DD - any date in the form of YYYY-MM-DD - note: anything that appears to start with YYYY will be treated as a date
182 |
183 | Field = "interests-X": where X is the Grouping Id from listInterestGroupings()
184 | Valid Op(erations): one / none / all
185 | Valid Values: a comma delimited of interest groups for the list - see listInterestGroupings()
186 |
187 | Field = "aim"
188 | Valid Op(erations): open / noopen / click / noclick
189 | Valid Values: "any" or a valid AIM-enabled Campaign that has been sent
190 |
191 | Field = "rating" : allows matching based on list member ratings
192 | Valid Op(erations): eq (=) / ne (!=) / gt (>) / lt (<)
193 | Valid Values: a number between 0 and 5
194 |
195 | Field = "ecomm_prod" or "ecomm_prod": allows matching product and category names from purchases
196 | Valid Op(erations):
197 | eq (=) / ne (!=) / gt (>) / lt (<) / like (like '%blah%') / nlike (not like '%blah%') / starts (like 'blah%') / ends (like '%blah')
198 | Valid Values: any string
199 |
200 | Field = "ecomm_spent_one" or "ecomm_spent_all" : allows matching purchase amounts on a single order or all orders
201 | Valid Op(erations): gt (>) / lt (<)
202 | Valid Values: a number
203 |
204 | Field = "ecomm_date" : allow matching based on order dates
205 | Valid Op(eration): eq (is) / gt (after) / lt (before)
206 | Valid Values:
207 | string YYYY-MM-DD - any date in the form of YYYY-MM-DD
208 |
209 | Field = "social_gender" : allows matching against the gender acquired from SocialPro
210 | Valid Op(eration): eq (is) / ne (is not)
211 | Valid Values: male, female
212 |
213 | Field = "social_age" : allows matching against the age acquired from SocialPro
214 | Valid Op(erations): eq (=) / ne (!=) / gt (>) / lt (<)
215 | Valid Values: any number
216 |
217 | Field = "social_influence" : allows matching against the influence acquired from SocialPro
218 | Valid Op(erations): eq (=) / ne (!=) / gt (>) / lt (<)
219 | Valid Values: a number between 0 and 5
220 |
221 | Field = "social_network" :
222 | Valid Op(erations): member (is a member of) / notmember (is not a member of)
223 | Valid Values: twitter, facebook, myspace, linkedin, flickr
224 |
225 | Field = "static_segment" :
226 | Valid Op(eration): eq (is in) / ne (is not in)
227 | Valid Values: an int - get from listStaticSegments()
228 |
229 | Field = An Address Merge Var. Use Merge0-Merge30 or the Custom Tag you've setup for your merge field - see listMergeVars(). Note, Address fields can still be used with the default operations below - this section is broken out solely to highlight the differences in using the geolocation routines.
230 | Valid Op(erations): geoin
231 | Valid Values: The number of miles an address should be within
232 | Extra Value: The Zip Code to be used as the center point
233 |
234 | Default Field = A Merge Var. Use Merge0-Merge30 or the Custom Tag you've setup for your merge field - see listMergeVars()
235 | Valid Op(erations):
236 | eq (=) / ne (!=) / gt (>) / lt (<) / like (like '%blah%') / nlike (not like '%blah%') / starts (like 'blah%') / ends (like '%blah')
237 | Valid Values: any string
238 | * @return int total The total number of subscribers matching your segmentation options
239 | */
240 | function campaignSegmentTest($list_id, $options) {
241 | $params = array();
242 | $params["list_id"] = $list_id;
243 | $params["options"] = $options;
244 | return $this->callServer("campaignSegmentTest", $params);
245 | }
246 |
247 | /**
248 | * Create a new draft campaign to send. You can not have more than 32,000 campaigns in your account.
249 | *
250 | * @section Campaign Related
251 | * @example mcapi_campaignCreate.php
252 | * @example xml-rpc_campaignCreate.php
253 | * @example xml-rpc_campaignCreateABSplit.php
254 | * @example xml-rpc_campaignCreateRss.php
255 | *
256 | * @param string $type the Campaign Type to create - one of "regular", "plaintext", "absplit", "rss", "trans", "auto"
257 | * @param array $options a hash of the standard options for this campaign :
258 | string list_id the list to send this campaign to- get lists using lists()
259 | string subject the subject line for your campaign message
260 | string from_email the From: email address for your campaign message
261 | string from_name the From: name for your campaign message (not an email address)
262 | string to_name the To: name recipients will see (not email address)
263 | int template_id optional - use this user-created template to generate the HTML content of the campaign (takes precendence over other template options)
264 | int gallery_template_id optional - use a template from the public gallery to generate the HTML content of the campaign (takes precendence over base template options)
265 | int base_template_id optional - use this a base/start-from-scratch template to generate the HTML content of the campaign
266 | int folder_id optional - automatically file the new campaign in the folder_id passed. Get using folders() - note that Campaigns and Autoresponders have separate folder setupsn
267 | array tracking optional - set which recipient actions will be tracked, as a struct of boolean values with the following keys: "opens", "html_clicks", and "text_clicks". By default, opens and HTML clicks will be tracked. Click tracking can not be disabled for Free accounts.
268 | string title optional - an internal name to use for this campaign. By default, the campaign subject will be used.
269 | boolean authenticate optional - set to true to enable SenderID, DomainKeys, and DKIM authentication, defaults to false.
270 | array analytics optional - if provided, use a struct with "service type" as a key and the "service tag" as a value. For Google, this should be "google"=>"your_google_analytics_key_here". Note that only "google" is currently supported - a Google Analytics tags will be added to all links in the campaign with this string attached. Others may be added in the future
271 | boolean auto_footer optional Whether or not we should auto-generate the footer for your content. Mostly useful for content from URLs or Imports
272 | boolean inline_css optional Whether or not css should be automatically inlined when this campaign is sent, defaults to false.
273 | boolean generate_text optional Whether of not to auto-generate your Text content from the HTML content. Note that this will be ignored if the Text part of the content passed is not empty, defaults to false.
274 | boolean auto_tweet optional If set, this campaign will be auto-tweeted when it is sent - defaults to false. Note that if a Twitter account isn't linked, this will be silently ignored.
275 | boolean timewarp optional If set, this campaign must be scheduled 24 hours in advance of sending - default to false. Only valid for "regular" campaigns and "absplit" campaigns that split on schedule_time.
276 | boolean ecomm360 optional If set, our Ecommerce360 tracking will be enabled for links in the campaign
277 |
278 | * @param array $content the content for this campaign - use a struct with the following keys:
279 | string html for pasted HTML content
280 | string text for the plain-text version
281 | string url to have us pull in content from a URL. Note, this will override any other content options - for lists with Email Format options, you'll need to turn on generate_text as well
282 | string archive to send a Base64 encoded archive file for us to import all media from. Note, this will override any other content options - for lists with Email Format options, you'll need to turn on generate_text as well
283 | string archive_type optional - only necessary for the "archive" option. Supported formats are: zip, tar.gz, tar.bz2, tar, tgz, tbz . If not included, we will default to zip
284 |
285 | If you chose a template instead of pasting in your HTML content, then use "html_" followed by the template sections as keys - for example, use a key of "html_MAIN" to fill in the "MAIN" section of a template. Supported template sections include: "html_HEADER", "html_MAIN", "html_SIDECOLUMN", and "html_FOOTER"
286 | * @param array $segment_opts optional - if you wish to do Segmentation with this campaign this array should contain: see campaignSegmentTest(). It's suggested that you test your options against campaignSegmentTest(). Also, "trans" campaigns do not support segmentation.
287 | * @param array $type_opts optional -
288 | For RSS Campaigns this, array should contain:
289 | string url the URL to pull RSS content from - it will be verified and must exist
290 | string schedule optional one of "daily", "weekly", "monthly" - defaults to "daily"
291 | string schedule_hour optional an hour between 0 and 24 - default to 4 (4am local time) - applies to all schedule types
292 | string schedule_weekday optional for "weekly" only, a number specifying the day of the week to send: 0 (Sunday) - 6 (Saturday) - defaults to 1 (Monday)
293 | string schedule_monthday optional for "monthly" only, a number specifying the day of the month to send (1 - 28) or "last" for the last day of a given month. Defaults to the 1st day of the month
294 |
295 | For A/B Split campaigns, this array should contain:
296 | string split_test The values to segment based on. Currently, one of: "subject", "from_name", "schedule". NOTE, for "schedule", you will need to call campaignSchedule() separately!
297 | string pick_winner How the winner will be picked, one of: "opens" (by the open_rate), "clicks" (by the click rate), "manual" (you pick manually)
298 | int wait_units optional the default time unit to wait before auto-selecting a winner - use "3600" for hours, "86400" for days. Defaults to 86400.
299 | int wait_time optional the number of units to wait before auto-selecting a winner - defaults to 1, so if not set, a winner will be selected after 1 Day.
300 | int split_size optional this is a percentage of what size the Campaign's List plus any segmentation options results in. "schedule" type forces 50%, all others default to 10%
301 | string from_name_a optional sort of, required when split_test is "from_name"
302 | string from_name_b optional sort of, required when split_test is "from_name"
303 | string from_email_a optional sort of, required when split_test is "from_name"
304 | string from_email_b optional sort of, required when split_test is "from_name"
305 | string subject_a optional sort of, required when split_test is "subject"
306 | string subject_b optional sort of, required when split_test is "subject"
307 |
308 | For AutoResponder campaigns, this array should contain:
309 | string offset-units one of "day", "week", "month", "year" - required
310 | string offset-time optional, sort of - the number of units must be a number greater than 0 for signup based autoresponders
311 | string offset-dir either "before" or "after"
312 | string event optional "signup" (default) to base this on double-optin signup, "date" or "annual" to base this on merge field in the list
313 | string event-datemerge optional sort of, this is required if the event is "date" or "annual"
314 |
315 | *
316 | * @return string the ID for the created campaign
317 | */
318 | function campaignCreate($type, $options, $content, $segment_opts=NULL, $type_opts=NULL) {
319 | $params = array();
320 | $params["type"] = $type;
321 | $params["options"] = $options;
322 | $params["content"] = $content;
323 | $params["segment_opts"] = $segment_opts;
324 | $params["type_opts"] = $type_opts;
325 | return $this->callServer("campaignCreate", $params);
326 | }
327 |
328 | /** Update just about any setting for a campaign that has not been sent. See campaignCreate() for details.
329 | *
330 | *
331 | * Caveats:
332 | * - If you set list_id, all segmentation options will be deleted and must be re-added.
333 | * - If you set template_id, you need to follow that up by setting it's 'content'
334 | * - If you set segment_opts, you should have tested your options against campaignSegmentTest() as campaignUpdate() will not allow you to set a segment that includes no members.
335 | * @section Campaign Related
336 | *
337 | * @example mcapi_campaignUpdate.php
338 | * @example mcapi_campaignUpdateAB.php
339 | * @example xml-rpc_campaignUpdate.php
340 | * @example xml-rpc_campaignUpdateAB.php
341 | *
342 | * @param string $cid the Campaign Id to update
343 | * @param string $name the parameter name ( see campaignCreate() ). For items in the options array, this will be that parameter's name (subject, from_email, etc.). Additional parameters will be that option name (content, segment_opts). "type_opts" will be the name of the type - rss, auto, trans, etc.
344 | * @param mixed $value an appropriate value for the parameter ( see campaignCreate() ). For items in the options array, this will be that parameter's value. For additional parameters, this is the same value passed to them.
345 | * @return boolean true if the update succeeds, otherwise an error will be thrown
346 | */
347 | function campaignUpdate($cid, $name, $value) {
348 | $params = array();
349 | $params["cid"] = $cid;
350 | $params["name"] = $name;
351 | $params["value"] = $value;
352 | return $this->callServer("campaignUpdate", $params);
353 | }
354 |
355 | /** Replicate a campaign.
356 | *
357 | * @section Campaign Related
358 | *
359 | * @example mcapi_campaignReplicate.php
360 | *
361 | * @param string $cid the Campaign Id to replicate
362 | * @return string the id of the replicated Campaign created, otherwise an error will be thrown
363 | */
364 | function campaignReplicate($cid) {
365 | $params = array();
366 | $params["cid"] = $cid;
367 | return $this->callServer("campaignReplicate", $params);
368 | }
369 |
370 | /** Delete a campaign. Seriously, "poof, gone!" - be careful!
371 | *
372 | * @section Campaign Related
373 | *
374 | * @example mcapi_campaignDelete.php
375 | *
376 | * @param string $cid the Campaign Id to delete
377 | * @return boolean true if the delete succeeds, otherwise an error will be thrown
378 | */
379 | function campaignDelete($cid) {
380 | $params = array();
381 | $params["cid"] = $cid;
382 | return $this->callServer("campaignDelete", $params);
383 | }
384 |
385 | /**
386 | * Get the list of campaigns and their details matching the specified filters
387 | *
388 | * @section Campaign Related
389 | * @example mcapi_campaigns.php
390 | * @example xml-rpc_campaigns.php
391 | *
392 | * @param array $filters a hash of filters to apply to this query - all are optional:
393 | string campaign_id optional - return a single campaign using a know campaign_id
394 | string list_id optional - the list to send this campaign to- get lists using lists(). Accepts multiples separated by commas when not using exact matching.
395 | int folder_id optional - only show campaigns from this folder id - get folders using campaignFolders(). Accepts multiples separated by commas when not using exact matching.
396 | int template_id optional - only show campaigns using this template id - get templates using templates(). Accepts multiples separated by commas when not using exact matching.
397 | string status optional - return campaigns of a specific status - one of "sent", "save", "paused", "schedule", "sending". Accepts multiples separated by commas when not using exact matching.
398 | string type optional - return campaigns of a specific type - one of "regular", "plaintext", "absplit", "rss", "trans", "auto". Accepts multiples separated by commas when not using exact matching.
399 | string from_name optional - only show campaigns that have this "From Name"
400 | string from_email optional - only show campaigns that have this "Reply-to Email"
401 | string title optional - only show campaigns that have this title
402 | string subject optional - only show campaigns that have this subject
403 | string sendtime_start optional - only show campaigns that have been sent since this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr)
404 | string sendtime_end optional - only show campaigns that have been sent before this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr)
405 | boolean exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to true. Using this disables the use of any filters that accept multiples.
406 | * @param int $start optional - control paging of campaigns, start results at this campaign #, defaults to 1st page of data (page 0)
407 | * @param int $limit optional - control paging of campaigns, number of campaigns to return with each call, defaults to 25 (max=1000)
408 | * @return array an array containing a count of all matching campaigns and the specific ones for the current page (see Returned Fields for description)
409 | * @returnf int total the total number of campaigns matching the filters passed in
410 | * @returnf array data the data for each campaign being returned
411 | string id Campaign Id (used for all other campaign functions)
412 | int web_id The Campaign id used in our web app, allows you to create a link directly to it
413 | string list_id The List used for this campaign
414 | int folder_id The Folder this campaign is in
415 | int template_id The Template this campaign uses
416 | string content_type How the campaign's content is put together - one of 'template', 'html', 'url'
417 | string title Title of the campaign
418 | string type The type of campaign this is (regular,plaintext,absplit,rss,inspection,trans,auto)
419 | string create_time Creation time for the campaign
420 | string send_time Send time for the campaign - also the scheduled time for scheduled campaigns.
421 | int emails_sent Number of emails email was sent to
422 | string status Status of the given campaign (save,paused,schedule,sending,sent)
423 | string from_name From name of the given campaign
424 | string from_email Reply-to email of the given campaign
425 | string subject Subject of the given campaign
426 | string to_name Custom "To:" email string using merge variables
427 | string archive_url Archive link for the given campaign
428 | boolean inline_css Whether or not the campaign content's css was auto-inlined
429 | string analytics Either "google" if enabled or "N" if disabled
430 | string analytics_tag The name/tag the campaign's links were tagged with if analytics were enabled.
431 | boolean authenticate Whether or not the campaign was authenticated
432 | boolean ecomm360 Whether or not ecomm360 tracking was appended to links
433 | boolean auto_tweet Whether or not the campaign was auto tweeted after sending
434 | string auto_fb_post A comma delimited list of Facebook Profile/Page Ids the campaign was posted to after sending. If not used, blank.
435 | boolean auto_footer Whether or not the auto_footer was manually turned on
436 | boolean timewarp Whether or not the campaign used Timewarp
437 | boolean timewarp_schedule The time, in GMT, that the Timewarp campaign is being sent. For A/B Split campaigns, this is blank and is instead in their schedule_a and schedule_b in the type_opts array
438 | array tracking containing "text_clicks", "html_clicks", and "opens" as boolean values representing whether or not they were enabled
439 | string segment_text a string marked-up with HTML explaining the segment used for the campaign in plain English
440 | array segment_opts the segment used for the campaign - can be passed to campaignSegmentTest() or campaignCreate()
441 | array type_opts the type-specific options for the campaign - can be passed to campaignCreate()
442 | */
443 | function campaigns($filters=array (
444 | ), $start=0, $limit=25) {
445 | $params = array();
446 | $params["filters"] = $filters;
447 | $params["start"] = $start;
448 | $params["limit"] = $limit;
449 | return $this->callServer("campaigns", $params);
450 | }
451 |
452 | /**
453 | * Given a list and a campaign, get all the relevant campaign statistics (opens, bounces, clicks, etc.)
454 | *
455 | * @section Campaign Stats
456 | *
457 | * @example mcapi_campaignStats.php
458 | * @example xml-rpc_campaignStats.php
459 | *
460 | * @param string $cid the campaign id to pull stats for (can be gathered using campaigns())
461 | * @return array struct of the statistics for this campaign
462 | * @returnf int syntax_errors Number of email addresses in campaign that had syntactical errors.
463 | * @returnf int hard_bounces Number of email addresses in campaign that hard bounced.
464 | * @returnf int soft_bounces Number of email addresses in campaign that soft bounced.
465 | * @returnf int unsubscribes Number of email addresses in campaign that unsubscribed.
466 | * @returnf int abuse_reports Number of email addresses in campaign that reported campaign for abuse.
467 | * @returnf int forwards Number of times email was forwarded to a friend.
468 | * @returnf int forwards_opens Number of times a forwarded email was opened.
469 | * @returnf int opens Number of times the campaign was opened.
470 | * @returnf date last_open Date of the last time the email was opened.
471 | * @returnf int unique_opens Number of people who opened the campaign.
472 | * @returnf int clicks Number of times a link in the campaign was clicked.
473 | * @returnf int unique_clicks Number of unique recipient/click pairs for the campaign.
474 | * @returnf date last_click Date of the last time a link in the email was clicked.
475 | * @returnf int users_who_clicked Number of unique recipients who clicked on a link in the campaign.
476 | * @returnf int emails_sent Number of email addresses campaign was sent to.
477 | * @returnf array absplit If this was an absplit campaign, stats for the A and B groups will be returned
478 | int bounces_a bounces for the A group
479 | int bounces_b bounces for the B group
480 | int forwards_a forwards for the A group
481 | int forwards_b forwards for the B group
482 | int abuse_reports_a abuse reports for the A group
483 | int abuse_reports_b abuse reports for the B group
484 | int unsubs_a unsubs for the A group
485 | int unsubs_b unsubs for the B group
486 | int recipients_click_a clicks for the A group
487 | int recipients_click_b clicks for the B group
488 | int forwards_opens_a opened forwards for the A group
489 | int forwards_opens_b opened forwards for the A group
490 | * @returnf array timewarp If this campaign was a Timewarp campaign, an array of stats from each timezone for it, with the GMT offset as they key. Each timezone will contain:
491 | int opens opens for this timezone
492 | string last_open the date/time of the last open for this timezone
493 | int unique_opens the unique opens for this timezone
494 | int clicks the total clicks for this timezone
495 | string last_click the date/time of the last click for this timezone
496 | int unique_opens the unique clicks for this timezone
497 | int bounces the total bounces for this timezone
498 | int total the total number of members sent to in this timezone
499 | int sent the total number of members delivered to in this timezone
500 | */
501 | function campaignStats($cid) {
502 | $params = array();
503 | $params["cid"] = $cid;
504 | return $this->callServer("campaignStats", $params);
505 | }
506 |
507 | /**
508 | * Get an array of the urls being tracked, and their click counts for a given campaign
509 | *
510 | * @section Campaign Stats
511 | *
512 | * @example mcapi_campaignClickStats.php
513 | * @example xml-rpc_campaignClickStats.php
514 | *
515 | * @param string $cid the campaign id to pull stats for (can be gathered using campaigns())
516 | * @return struct urls will be keys and contain their associated statistics:
517 | * @returnf int clicks Number of times the specific link was clicked
518 | * @returnf int unique Number of unique people who clicked on the specific link
519 | */
520 | function campaignClickStats($cid) {
521 | $params = array();
522 | $params["cid"] = $cid;
523 | return $this->callServer("campaignClickStats", $params);
524 | }
525 |
526 | /**
527 | * Get the top 5 performing email domains for this campaign. Users want more than 5 should use campaign campaignEmailStatsAIM()
528 | * or campaignEmailStatsAIMAll() and generate any additional stats they require.
529 | *
530 | * @section Campaign Stats
531 | *
532 | * @example mcapi_campaignEmailDomainPerformance.php
533 | *
534 | * @param string $cid the campaign id to pull email domain performance for (can be gathered using campaigns())
535 | * @return array domains email domains and their associated stats
536 | * @returnf string domain Domain name or special "Other" to roll-up stats past 5 domains
537 | * @returnf int total_sent Total Email across all domains - this will be the same in every row
538 | * @returnf int emails Number of emails sent to this domain
539 | * @returnf int bounces Number of bounces
540 | * @returnf int opens Number of opens
541 | * @returnf int clicks Number of clicks
542 | * @returnf int unsubs Number of unsubs
543 | * @returnf int delivered Number of deliveries
544 | * @returnf int emails_pct Percentage of emails that went to this domain (whole number)
545 | * @returnf int bounces_pct Percentage of bounces from this domain (whole number)
546 | * @returnf int opens_pct Percentage of opens from this domain (whole number)
547 | * @returnf int clicks_pct Percentage of clicks from this domain (whole number)
548 | * @returnf int unsubs_pct Percentage of unsubs from this domain (whole number)
549 | */
550 | function campaignEmailDomainPerformance($cid) {
551 | $params = array();
552 | $params["cid"] = $cid;
553 | return $this->callServer("campaignEmailDomainPerformance", $params);
554 | }
555 |
556 | /**
557 | * Get all email addresses the campaign was successfully sent to (ie, no bounces)
558 | *
559 | * @section Campaign Stats
560 | *
561 | * @param string $cid the campaign id to pull members for (can be gathered using campaigns())
562 | * @param string $status optional the status to pull - one of 'sent', 'hard' (bounce), or 'soft' (bounce). By default, all records are returned
563 | * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
564 | * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
565 | * @return array a total of all matching emails and the specific emails for this page
566 | * @returnf int total the total number of members for the campaign and status
567 | * @returnf array data the full campaign member records
568 | string email the email address sent to
569 | string status the status of the send - one of 'sent', 'hard', 'soft'
570 | string absplit_group if this was an absplit campaign, one of 'a','b', or 'winner'
571 | string tz_group if this was an timewarp campaign the timezone GMT offset the member was included in
572 | */
573 | function campaignMembers($cid, $status=NULL, $start=0, $limit=1000) {
574 | $params = array();
575 | $params["cid"] = $cid;
576 | $params["status"] = $status;
577 | $params["start"] = $start;
578 | $params["limit"] = $limit;
579 | return $this->callServer("campaignMembers", $params);
580 | }
581 |
582 | /**
583 | * DEPRECATED Get all email addresses with Hard Bounces for a given campaign
584 | *
585 | * @deprecated See campaignMembers() for a replacement
586 | *
587 | * @section Campaign Stats
588 | *
589 | * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
590 | * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
591 | * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
592 | * @return array a total of all hard bounced emails and the specific emails for this page
593 | * @returnf int total the total number of hard bounces for the campaign
594 | * @returnf array data the full email addresses that bounced
595 | string email the email address that bounced
596 | */
597 | function campaignHardBounces($cid, $start=0, $limit=1000) {
598 | $params = array();
599 | $params["cid"] = $cid;
600 | $params["start"] = $start;
601 | $params["limit"] = $limit;
602 | return $this->callServer("campaignHardBounces", $params);
603 | }
604 |
605 | /**
606 | * DEPRECATED Get all email addresses with Soft Bounces for a given campaign
607 | *
608 | * @deprecated See campaignMembers() for a replacement
609 | *
610 | * @section Campaign Stats
611 | *
612 | * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
613 | * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
614 | * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
615 | * @return array a total of all soft bounced emails and the specific emails for this page
616 | * @returnf int total the total number of soft bounces for the campaign
617 | * @returnf array data the full email addresses that bounced
618 | string email the email address that bounced
619 | */
620 | function campaignSoftBounces($cid, $start=0, $limit=1000) {
621 | $params = array();
622 | $params["cid"] = $cid;
623 | $params["start"] = $start;
624 | $params["limit"] = $limit;
625 | return $this->callServer("campaignSoftBounces", $params);
626 | }
627 |
628 | /**
629 | * Get all unsubscribed email addresses for a given campaign
630 | *
631 | * @section Campaign Stats
632 | *
633 | * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
634 | * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
635 | * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
636 | * @return array email addresses that unsubscribed from this campaign along with reasons, if given
637 | * @return array a total of all unsubscribed emails and the specific emails for this page
638 | * @returnf int total the total number of unsubscribes for the campaign
639 | * @returnf array data the full email addresses that unsubscribed
640 | string email the email address that unsubscribed
641 | string reason For unsubscribes only - the reason collected for the unsubscribe. If populated, one of 'NORMAL','NOSIGNUP','INAPPROPRIATE','SPAM','OTHER'
642 | string reason_text For unsubscribes only - if the reason is OTHER, the text entered.
643 | */
644 | function campaignUnsubscribes($cid, $start=0, $limit=1000) {
645 | $params = array();
646 | $params["cid"] = $cid;
647 | $params["start"] = $start;
648 | $params["limit"] = $limit;
649 | return $this->callServer("campaignUnsubscribes", $params);
650 | }
651 |
652 | /**
653 | * Get all email addresses that complained about a given campaign
654 | *
655 | * @section Campaign Stats
656 | *
657 | * @example mcapi_campaignAbuseReports.php
658 | *
659 | * @param string $cid the campaign id to pull abuse reports for (can be gathered using campaigns())
660 | * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
661 | * @param int $limit optional for large data sets, the number of results to return - defaults to 500, upper limit set at 1000
662 | * @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in GMT
663 | * @return array reports the abuse reports for this campaign
664 | * @returnf string date date/time the abuse report was received and processed
665 | * @returnf string email the email address that reported abuse
666 | * @returnf string type an internal type generally specifying the orginating mail provider - may not be useful outside of filling report views
667 | */
668 | function campaignAbuseReports($cid, $since=NULL, $start=0, $limit=500) {
669 | $params = array();
670 | $params["cid"] = $cid;
671 | $params["since"] = $since;
672 | $params["start"] = $start;
673 | $params["limit"] = $limit;
674 | return $this->callServer("campaignAbuseReports", $params);
675 | }
676 |
677 | /**
678 | * Retrieve the text presented in our app for how a campaign performed and any advice we may have for you - best
679 | * suited for display in customized reports pages. Note: some messages will contain HTML - clean tags as necessary
680 | *
681 | * @section Campaign Stats
682 | *
683 | * @example mcapi_campaignAdvice.php
684 | *
685 | * @param string $cid the campaign id to pull advice text for (can be gathered using campaigns())
686 | * @return array advice on the campaign's performance
687 | * @returnf msg the advice message
688 | * @returnf type the "type" of the message. one of: negative, positive, or neutral
689 | */
690 | function campaignAdvice($cid) {
691 | $params = array();
692 | $params["cid"] = $cid;
693 | return $this->callServer("campaignAdvice", $params);
694 | }
695 |
696 | /**
697 | * Retrieve the Google Analytics data we've collected for this campaign. Note, requires Google Analytics Add-on to be installed and configured.
698 | *
699 | * @section Campaign Stats
700 | *
701 | * @example mcapi_campaignAnalytics.php
702 | *
703 | * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
704 | * @return array analytics we've collected for the passed campaign.
705 | * @returnf int visits number of visits
706 | * @returnf int pages number of page views
707 | * @returnf int new_visits new visits recorded
708 | * @returnf int bounces vistors who "bounced" from your site
709 | * @returnf double time_on_site the total time visitors spent on your sites
710 | * @returnf int goal_conversions number of goals converted
711 | * @returnf double goal_value value of conversion in dollars
712 | * @returnf double revenue revenue generated by campaign
713 | * @returnf int transactions number of transactions tracked
714 | * @returnf int ecomm_conversions number Ecommerce transactions tracked
715 | * @returnf array goals an array containing goal names and number of conversions
716 | */
717 | function campaignAnalytics($cid) {
718 | $params = array();
719 | $params["cid"] = $cid;
720 | return $this->callServer("campaignAnalytics", $params);
721 | }
722 |
723 | /**
724 | * Retrieve the countries and number of opens tracked for each. Email address are not returned.
725 | *
726 | * @section Campaign Stats
727 | *
728 | *
729 | * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
730 | * @return array countries an array of countries where opens occurred
731 | * @returnf string code The ISO3166 2 digit country code
732 | * @returnf string name A version of the country name, if we have it
733 | * @returnf int opens The total number of opens that occurred in the country
734 | * @returnf bool region_detail Whether or not a subsequent call to campaignGeoOpensByCountry() will return anything
735 | */
736 | function campaignGeoOpens($cid) {
737 | $params = array();
738 | $params["cid"] = $cid;
739 | return $this->callServer("campaignGeoOpens", $params);
740 | }
741 |
742 | /**
743 | * Retrieve the regions and number of opens tracked for a certain country. Email address are not returned.
744 | *
745 | * @section Campaign Stats
746 | *
747 | *
748 | * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
749 | * @param string $code An ISO3166 2 digit country code
750 | * @return array regions an array of regions within the provided country where opens occurred.
751 | * @returnf string code An internal code for the region. When this is blank, it indicates we know the country, but not the region
752 | * @returnf string name The name of the region, if we have one. For blank "code" values, this will be "Rest of Country"
753 | * @returnf int opens The total number of opens that occurred in the country
754 | */
755 | function campaignGeoOpensForCountry($cid, $code) {
756 | $params = array();
757 | $params["cid"] = $cid;
758 | $params["code"] = $code;
759 | return $this->callServer("campaignGeoOpensForCountry", $params);
760 | }
761 |
762 | /**
763 | * Retrieve the tracked eepurl mentions on Twitter
764 | *
765 | * @section Campaign Stats
766 | *
767 | *
768 | * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
769 | * @return array stats an array containing tweets, retweets, clicks, and referrer related to using the campaign's eepurl
770 | * @returnf array twitter various Twitter related stats
771 | int tweets Total number of tweets seen
772 | string first_tweet date and time of the first tweet seen
773 | string last_tweet date and time of the last tweet seen
774 | int retweets Total number of retweets seen
775 | string first_retweet date and time of the first retweet seen
776 | string last_retweet date and time of the last retweet seen
777 | array statuses an array of statuses recorded inclduing the status, screen_name, status_id, and datetime fields plus an is_retweet flag
778 | * @returnf array clicks stats related to click-throughs on the eepurl
779 | int clicks Total number of clicks seen
780 | string first_click date and time of the first click seen
781 | string last_click date and time of the first click seen
782 | array locations an array of geographic locations including country, region, and total clicks
783 | * @returnf array referrers an array of arrays, each containing
784 | string referrer the referrer, truncated to 100 bytes
785 | int clicks Total number of clicks seen from this referrer
786 | string first_click date and time of the first click seen from this referrer
787 | string last_click date and time of the first click seen from this referrer
788 | */
789 | function campaignEepUrlStats($cid) {
790 | $params = array();
791 | $params["cid"] = $cid;
792 | return $this->callServer("campaignEepUrlStats", $params);
793 | }
794 |
795 | /**
796 | * Retrieve the most recent full bounce message for a specific email address on the given campaign.
797 | * Messages over 30 days old are subject to being removed
798 | *
799 | *
800 | * @section Campaign Stats
801 | *
802 | * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
803 | * @param string $email the email address or unique id of the member to pull a bounce message for.
804 | * @return array the full bounce message for this email+campaign along with some extra data.
805 | * @returnf string date date/time the bounce was received and processed
806 | * @returnf string email the email address that bounced
807 | * @returnf string message the entire bounce message received
808 | */
809 | function campaignBounceMessage($cid, $email) {
810 | $params = array();
811 | $params["cid"] = $cid;
812 | $params["email"] = $email;
813 | return $this->callServer("campaignBounceMessage", $params);
814 | }
815 |
816 | /**
817 | * Retrieve the full bounce messages for the given campaign. Note that this can return very large amounts
818 | * of data depending on how large the campaign was and how much cruft the bounce provider returned. Also,
819 | * message over 30 days old are subject to being removed
820 | *
821 | * @section Campaign Stats
822 | *
823 | * @example mcapi_campaignBounceMessages.php
824 | *
825 | * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
826 | * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
827 | * @param int $limit optional for large data sets, the number of results to return - defaults to 25, upper limit set at 50
828 | * @param string $since optional pull only messages since this time - use YYYY-MM-DD format in GMT (we only store the date, not the time)
829 | * @return array bounces the full bounce messages for this campaign
830 | * @returnf int total that total number of bounce messages for the campaign
831 | * @returnf array data an array containing the data for this page
832 | string date date/time the bounce was received and processed
833 | string email the email address that bounced
834 | string message the entire bounce message received
835 | */
836 | function campaignBounceMessages($cid, $start=0, $limit=25, $since=NULL) {
837 | $params = array();
838 | $params["cid"] = $cid;
839 | $params["start"] = $start;
840 | $params["limit"] = $limit;
841 | $params["since"] = $since;
842 | return $this->callServer("campaignBounceMessages", $params);
843 | }
844 |
845 | /**
846 | * Retrieve the Ecommerce Orders tracked by campaignEcommOrderAdd()
847 | *
848 | * @section Campaign Stats
849 | *
850 | * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
851 | * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
852 | * @param int $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 500
853 | * @param string $since optional pull only messages since this time - use YYYY-MM-DD HH:II:SS format in GMT
854 | * @return array the total matching orders and the specific orders for the requested page
855 | * @returnf int total the total matching orders
856 | * @returnf array data the actual data for each order being returned
857 | string store_id the store id generated by the plugin used to uniquely identify a store
858 | string store_name the store name collected by the plugin - often the domain name
859 | string order_id the internal order id the store tracked this order by
860 | string email the email address that received this campaign and is associated with this order
861 | double order_total the order total
862 | double tax_total the total tax for the order (if collected)
863 | double ship_total the shipping total for the order (if collected)
864 | string order_date the date the order was tracked - from the store if possible, otherwise the GMT time we recieved it
865 | array lines containing detail of the order - product, category, quantity, item cost
866 | */
867 | function campaignEcommOrders($cid, $start=0, $limit=100, $since=NULL) {
868 | $params = array();
869 | $params["cid"] = $cid;
870 | $params["start"] = $start;
871 | $params["limit"] = $limit;
872 | $params["since"] = $since;
873 | return $this->callServer("campaignEcommOrders", $params);
874 | }
875 |
876 | /**
877 | * Get the URL to a customized VIP Report for the specified campaign and optionally send an email to someone with links to it. Note subsequent calls will overwrite anything already set for the same campign (eg, the password)
878 | *
879 | * @section Campaign Related
880 | *
881 | * @param string $cid the campaign id to share a report for (can be gathered using campaigns())
882 | * @param array $opts optional various parameters which can be used to configure the shared report
883 | string header_type optional - "text" or "image', defaults to "text'
884 | string header_data optional - if "header_type" is text, the text to display. if "header_type" is "image" a valid URL to an image file. Note that images will be resized to be no more than 500x150. Defaults to the Accounts Company Name.
885 | boolean secure optional - whether to require a password for the shared report. defaults to "true"
886 | string password optional - if secure is true and a password is not included, we will generate one. It is always returned.
887 | string to_email optional - optional, email address to share the report with - no value means an email will not be sent
888 | array theme optional - an array containing either 3 or 6 character color code values for: "bg_color", "header_color", "current_tab", "current_tab_text", "normal_tab", "normal_tab_text", "hover_tab", "hover_tab_text"
889 | string css_url optional - a link to an external CSS file to be included after our default CSS (http://vip-reports.net/css/vip.css) only if loaded via the "secure_url" - max 255 bytes
890 | * @return struct Struct containing details for the shared report
891 | * @returnf string title The Title of the Campaign being shared
892 | * @returnf string url The URL to the shared report
893 | * @returnf string secure_url The URL to the shared report, including the password (good for loading in an IFRAME). For non-secure reports, this will not be returned
894 | * @returnf string password If secured, the password for the report, otherwise this field will not be returned
895 | */
896 | function campaignShareReport($cid, $opts=array (
897 | )) {
898 | $params = array();
899 | $params["cid"] = $cid;
900 | $params["opts"] = $opts;
901 | return $this->callServer("campaignShareReport", $params);
902 | }
903 |
904 | /**
905 | * Get the content (both html and text) for a campaign either as it would appear in the campaign archive or as the raw, original content
906 | *
907 | * @section Campaign Related
908 | *
909 | * @param string $cid the campaign id to get content for (can be gathered using campaigns())
910 | * @param bool $for_archive optional controls whether we return the Archive version (true) or the Raw version (false), defaults to true
911 | * @return struct Struct containing all content for the campaign (see Returned Fields for details
912 | * @returnf string html The HTML content used for the campgain with merge tags intact
913 | * @returnf string text The Text content used for the campgain with merge tags intact
914 | */
915 | function campaignContent($cid, $for_archive=true) {
916 | $params = array();
917 | $params["cid"] = $cid;
918 | $params["for_archive"] = $for_archive;
919 | return $this->callServer("campaignContent", $params);
920 | }
921 |
922 | /**
923 | * Get the HTML template content sections for a campaign. Note that this will return very jagged, non-standard results based on the template
924 | * a campaign is using. You only want to use this if you want to allow editing template sections in your applicaton.
925 | *
926 | * @section Campaign Related
927 | *
928 | * @param string $cid the campaign id to get content for (can be gathered using campaigns())
929 | * @return array array containing all content section for the campaign -
930 | */
931 | function campaignTemplateContent($cid) {
932 | $params = array();
933 | $params["cid"] = $cid;
934 | return $this->callServer("campaignTemplateContent", $params);
935 | }
936 |
937 | /**
938 | * Retrieve the list of email addresses that opened a given campaign with how many times they opened - note: this AIM function is free and does
939 | * not actually require the AIM module to be installed
940 | *
941 | * @section Campaign Report Data
942 | *
943 | * @param string $cid the campaign id to get opens for (can be gathered using campaigns())
944 | * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
945 | * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
946 | * @return array array containing the total records matched and the specific records for this page
947 | * @returnf int total the total number of records matched
948 | * @returnf array data the actual opens data, including:
949 | string email Email address that opened the campaign
950 | int open_count Total number of times the campaign was opened by this email address
951 | */
952 | function campaignOpenedAIM($cid, $start=0, $limit=1000) {
953 | $params = array();
954 | $params["cid"] = $cid;
955 | $params["start"] = $start;
956 | $params["limit"] = $limit;
957 | return $this->callServer("campaignOpenedAIM", $params);
958 | }
959 |
960 | /**
961 | * Retrieve the list of email addresses that did not open a given campaign
962 | *
963 | * @section Campaign Report Data
964 | *
965 | * @param string $cid the campaign id to get no opens for (can be gathered using campaigns())
966 | * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
967 | * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
968 | * @return array array containing the total records matched and the specific records for this page
969 | * @returnf int total the total number of records matched
970 | * @returnf array data the email addresses that did not open the campaign
971 | string email Email address that opened the campaign
972 | */
973 | function campaignNotOpenedAIM($cid, $start=0, $limit=1000) {
974 | $params = array();
975 | $params["cid"] = $cid;
976 | $params["start"] = $start;
977 | $params["limit"] = $limit;
978 | return $this->callServer("campaignNotOpenedAIM", $params);
979 | }
980 |
981 | /**
982 | * Return the list of email addresses that clicked on a given url, and how many times they clicked
983 | *
984 | * @section Campaign Report Data
985 | *
986 | * @param string $cid the campaign id to get click stats for (can be gathered using campaigns())
987 | * @param string $url the URL of the link that was clicked on
988 | * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
989 | * @param int $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
990 | * @return array array containing the total records matched and the specific records for this page
991 | * @returnf int total the total number of records matched
992 | * @returnf array data the email addresses that did not open the campaign
993 | string email Email address that opened the campaign
994 | int clicks Total number of times the URL was clicked on by this email address
995 | */
996 | function campaignClickDetailAIM($cid, $url, $start=0, $limit=1000) {
997 | $params = array();
998 | $params["cid"] = $cid;
999 | $params["url"] = $url;
1000 | $params["start"] = $start;
1001 | $params["limit"] = $limit;
1002 | return $this->callServer("campaignClickDetailAIM", $params);
1003 | }
1004 |
1005 | /**
1006 | * Given a campaign and email address, return the entire click and open history with timestamps, ordered by time
1007 | *
1008 | * @section Campaign Report Data
1009 | *
1010 | * @param string $cid the campaign id to get stats for (can be gathered using campaigns())
1011 | * @param array $email_address an array of up to 50 email addresses to check OR the email "id" returned from listMemberInfo, Webhooks, and Campaigns. For backwards compatibility, if a string is passed, it will be treated as an array with a single element (will not work with XML-RPC).
1012 | * @return array an array with the keys listed in Returned Fields below
1013 | * @returnf int success the number of email address records found
1014 | * @returnf int error the number of email address records which could not be found
1015 | * @returnf array data arrays containing the actions (opens and clicks) that the email took, with timestamps
1016 | string action The action taken (open or click)
1017 | string timestamp Time the action occurred
1018 | string url For clicks, the URL that was clicked
1019 | */
1020 | function campaignEmailStatsAIM($cid, $email_address) {
1021 | $params = array();
1022 | $params["cid"] = $cid;
1023 | $params["email_address"] = $email_address;
1024 | return $this->callServer("campaignEmailStatsAIM", $params);
1025 | }
1026 |
1027 | /**
1028 | * Given a campaign and correct paging limits, return the entire click and open history with timestamps, ordered by time,
1029 | * for every user a campaign was delivered to.
1030 | *
1031 | * @section Campaign Report Data
1032 | * @example mcapi_campaignEmailStatsAIMAll.php
1033 | *
1034 | * @param string $cid the campaign id to get stats for (can be gathered using campaigns())
1035 | * @param int $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
1036 | * @param int $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 1000
1037 | * @return array Array containing a total record count and data including the actions (opens and clicks) for each email, with timestamps
1038 | * @returnf int total the total number of records
1039 | * @returnf array data each record with their details:
1040 | string action The action taken (open or click)
1041 | string timestamp Time the action occurred
1042 | string url For clicks, the URL that was clicked
1043 | */
1044 | function campaignEmailStatsAIMAll($cid, $start=0, $limit=100) {
1045 | $params = array();
1046 | $params["cid"] = $cid;
1047 | $params["start"] = $start;
1048 | $params["limit"] = $limit;
1049 | return $this->callServer("campaignEmailStatsAIMAll", $params);
1050 | }
1051 |
1052 | /**
1053 | * Attach Ecommerce Order Information to a Campaign. This will generall be used by ecommerce package plugins
1054 | * that we provide or by 3rd part system developers.
1055 | * @section Campaign Related
1056 | *
1057 | * @param array $order an array of information pertaining to the order that has completed. Use the following keys:
1058 | string id the Order Id
1059 | string campaign_id the Campaign Id to track this order with (see the "mc_cid" query string variable a campaign passes)
1060 | string email_id the Email Id of the subscriber we should attach this order to (see the "mc_eid" query string variable a campaign passes)
1061 | double total The Order Total (ie, the full amount the customer ends up paying)
1062 | string order_date optional the date of the order - if this is not provided, we will default the date to now
1063 | double shipping optional the total paid for Shipping Fees
1064 | double tax optional the total tax paid
1065 | string store_id a unique id for the store sending the order in (20 bytes max)
1066 | string store_name optional a "nice" name for the store - typically the base web address (ie, "store.mailchimp.com"). We will automatically update this if it changes (based on store_id)
1067 | string plugin_id the MailChimp assigned Plugin Id. Get yours by registering here
1068 | array items the individual line items for an order using these keys:
1069 | |
1070 | int line_num optional the line number of the item on the order. We will generate these if they are not passed
1071 | int product_id the store's internal Id for the product. Lines that do no contain this will be skipped
1072 | string product_name the product name for the product_id associated with this item. We will auto update these as they change (based on product_id)
1073 | int category_id the store's internal Id for the (main) category associated with this product. Our testing has found this to be a "best guess" scenario
1074 | string category_name the category name for the category_id this product is in. Our testing has found this to be a "best guess" scenario. Our plugins walk the category heirarchy up and send "Root - SubCat1 - SubCat4", etc.
1075 | double qty the quantity of the item ordered
1076 | double cost the cost of a single item (ie, not the extended cost of the line)
1077 | |
|
2223 | int line_num optional the line number of the item on the order. We will generate these if they are not passed
2224 | int product_id the store's internal Id for the product. Lines that do no contain this will be skipped
2225 | string product_name the product name for the product_id associated with this item. We will auto update these as they change (based on product_id)
2226 | int category_id the store's internal Id for the (main) category associated with this product. Our testing has found this to be a "best guess" scenario
2227 | string category_name the category name for the category_id this product is in. Our testing has found this to be a "best guess" scenario. Our plugins walk the category heirarchy up and send "Root - SubCat1 - SubCat4", etc.
2228 | double qty the quantity of the item ordered
2229 | double cost the cost of a single item (ie, not the extended cost of the line)
2230 | |