« Back to Documentation Overview

campaignCreate – v1.3

 campaignCreate(string apikey, string type, array options, array content, array segment_opts, array type_opts)

Create a new draft campaign to send. You can not have more than 32,000 campaigns in your account.

Section
Campaign Related
Parameters
apikey a valid API Key for your user account. Get by visiting your API dashboard
type the Campaign Type to create - one of "regular", "plaintext", "absplit", "rss", "auto"
options a hash of the standard options for this campaign :
stringlist_idthe list to send this campaign to- get lists using lists()
stringsubjectthe subject line for your campaign message
stringfrom_emailthe From: email address for your campaign message
stringfrom_namethe From: name for your campaign message (not an email address)
stringto_namethe To: name recipients will see (not email address)
inttemplate_idoptional - use this user-created template to generate the HTML content of the campaign (takes precendence over other template options)
intgallery_template_idoptional - use a template from the public gallery to generate the HTML content of the campaign (takes precendence over base template options)
intbase_template_idoptional - use this a base/start-from-scratch template to generate the HTML content of the campaign
intfolder_idoptional - automatically file the new campaign in the folder_id passed. Get using folders() - note that Campaigns and Autoresponders have separate folder setupsn
arraytrackingoptional - 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.
stringtitleoptional - an internal name to use for this campaign. By default, the campaign subject will be used.
booleanauthenticateoptional - set to true to enable SenderID, DomainKeys, and DKIM authentication, defaults to false.
arrayanalyticsoptional - if provided, use a struct with "service type" as a key and the "service tag" as a value. Use "google" for Google Analytics, "clicktale" for ClickTale, and "gooal" for Goo.al tracking. The "tag" is any custom text (up to 50 characters) that should be included.
booleanauto_footeroptional - Whether or not we should auto-generate the footer for your content. Mostly useful for content from URLs or Imports
booleaninline_cssoptional - Whether or not css should be automatically inlined when this campaign is sent, defaults to false.
booleangenerate_textoptional - 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.
booleanauto_tweetoptional - 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.
arrayauto_fb_postoptional - If set, this campaign will be auto-posted to the page_ids contained in the array. If a Facebook account isn't linked or the account does not have permission to post to the page_ids requested, those failures will be silently ignored.
booleanfb_commentsoptional - If true, the Facebook comments (and thus the archive bar will be displayed. If false, Facebook comments will not be enabled (does not imply no archive bar, see previous link). Defaults to "true".
booleantimewarpoptional - 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.
booleanecomm360optional - If set, our Ecommerce360 tracking will be enabled for links in the campaign
arraycrm_trackingoptional - If set, enable CRM tracking for:
arraysalesforceoptional - Enable SalesForce push back
boolcampaignoptional - if true, create a Campaign object and update it with aggregate stats
boolnotesoptional - if true, attempt to update Contact notes based on email address
arrayhighriseoptional - Enable Highrise push back
boolcampaignoptional - if true, create a Kase object and update it with aggregate stats
boolnotesoptional - if true, attempt to update Contact notes based on email address
arraycapsuleoptional - Enable Capsule push back (only notes are supported)
boolnotesoptional - if true, attempt to update Contact notes based on email address
content the content for this campaign - use a struct with the following keys:
stringhtmlfor pasted HTML content
stringtextfor the plain-text version
stringurlto 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
stringarchiveto 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
stringarchive_typeoptional - 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
 
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.
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().
type_opts optional -
For RSS Campaigns this, array should contain:
stringurlthe URL to pull RSS content from - it will be verified and must exist
stringscheduleoptional - one of "daily", "weekly", "monthly" - defaults to "daily"
stringschedule_houroptional - an hour between 0 and 24 - default to 4 (4am local time) - applies to all schedule types
stringschedule_weekdayoptional - for "weekly" only, a number specifying the day of the week to send: 0 (Sunday) - 6 (Saturday) - defaults to 1 (Monday)
stringschedule_monthdayoptional - 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
arraydaysoptional - used for "daily" schedules only, an array of the ISO-8601 weekday numbers to send on
bool1optional - Monday, defaults to true
bool2optional - Tuesday, defaults to true
bool3optional - Wednesday, defaults to true
bool4optional - Thursday, defaults to true
bool5optional - Friday, defaults to true
bool6optional - Saturday, defaults to true
bool7optional - Sunday, defaults to true
 
For A/B Split campaigns, this array should contain:
stringsplit_testThe values to segment based on. Currently, one of: "subject", "from_name", "schedule". NOTE, for "schedule", you will need to call campaignSchedule() separately!
stringpick_winnerHow the winner will be picked, one of: "opens" (by the open_rate), "clicks" (by the click rate), "manual" (you pick manually)
intwait_unitsoptional - the default time unit to wait before auto-selecting a winner - use "3600" for hours, "86400" for days. Defaults to 86400.
intwait_timeoptional - 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.
intsplit_sizeoptional - 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%
stringfrom_name_aoptional - sort of, required when split_test is "from_name"
stringfrom_name_boptional - sort of, required when split_test is "from_name"
stringfrom_email_aoptional - sort of, required when split_test is "from_name"
stringfrom_email_boptional - sort of, required when split_test is "from_name"
stringsubject_aoptional - sort of, required when split_test is "subject"
stringsubject_boptional - sort of, required when split_test is "subject"
 
For AutoResponder campaigns, this array should contain:
stringoffset-unitsone of "hourly", "day", "week", "month", "year" - required
stringoffset-timeoptional - , sort of - the number of units must be a number greater than 0 for signup based autoresponders, ignored for "hourly"
stringoffset-direither "before" or "after", ignored for "hourly"
stringeventoptional - "signup" (default) to base this members added to a list, "date", "annual", or "birthday" to base this on merge field in the list, "campaignOpen" or "campaignClicka" to base this on any activity for a campaign, "campaignClicko" to base this on clicks on a specific URL in a campaign, "mergeChanged" to base this on a specific merge field being changed to a specific value
stringevent-datemergeoptional - sort of, this is required if the event is "date", "annual", "birthday", or "mergeChanged"
stringcampaign_idoptional - sort of, required for "campaignOpen", "campaignClicka", or "campaignClicko"
stringcampaign_urloptional - sort of, required for "campaignClicko"
intschedule_hourThe hour of the day - 24 hour format in GMT - the autoresponder should be triggered, ignored for "hourly"
booleanuse_import_timewhether or not imported subscribers (ie, any non-double optin subscribers) will receive
arraydaysoptional - used for "daily" schedules only, an array of the ISO-8601 weekday numbers to send on
bool1optional - Monday, defaults to true
bool2optional - Tuesday, defaults to true
bool3optional - Wednesday, defaults to true
bool4optional - Thursday, defaults to true
bool5optional - Friday, defaults to true
bool6optional - Saturday, defaults to true
bool7optional - Sunday, defaults to true
Returns
string the ID for the created campaign

Examples (4)

download example code

[1] mcapi_campaignCreate.php

  1. <?php
  2. /**
  3. This Example shows how to create a basic campaign via the MCAPI class.
  4. **/
  5. require_once 'inc/MCAPI.class.php';
  6. require_once 'inc/config.inc.php'; //contains apikey
  7.  
  8. $api = new MCAPI($apikey);
  9.  
  10. $type = 'regular';
  11.  
  12. $opts['list_id'] = 'f9ee6d8616';
  13. $opts['subject'] = 'Test Newsletter Subject';
  14. $opts['from_email'] = 'mailchimp@example.org';
  15. $opts['from_name'] = 'ACME, Inc.';
  16.  
  17. $opts['tracking']=array('opens' => true, 'html_clicks' => true, 'text_clicks' => false);
  18.  
  19. $opts['authenticate'] = true;
  20. $opts['analytics'] = array('google'=>'my_google_analytics_key');
  21. $opts['title'] = 'Test Newsletter Title';
  22.  
  23. $content = array('html'=>'some pretty html content *|UNSUB|* message',
  24. 'text' => 'text text text *|UNSUB|*'
  25. );
  26. /** OR we could use this:
  27. $content = array('html_main'=>'some pretty html content',
  28. 'html_sidecolumn' => 'this goes in a side column',
  29. 'html_header' => 'this gets placed in the header',
  30. 'html_footer' => 'the footer with an *|UNSUB|* message',
  31. 'text' => 'text content text content *|UNSUB|*'
  32. );
  33. $opts['template_id'] = "1";
  34. **/
  35.  
  36. $retval = $api->campaignCreate($type, $opts, $content);
  37.  
  38. if ($api->errorCode){
  39. echo "Unable to Create New Campaign!";
  40. echo "\n\tCode=".$api->errorCode;
  41. echo "\n\tMsg=".$api->errorMessage."\n";
  42. } else {
  43. echo "New Campaign ID:".$retval."\n";
  44. }
  45.  
  46. ?>
  47.  

[2] xml-rpc_campaignCreate.php

  1. <?php
  2. /**
  3. This Example shows how create a basic campaign using XML-RPC.
  4. Note that we are using the PEAR XML-RPC client and recommend others do as well.
  5. **/
  6. require_once 'XML/RPC2/Client.php';
  7. require_once 'inc/config.inc.php';
  8. try {
  9. $client = XML_RPC2_Client::create($apiUrl);
  10.  
  11. $type = 'regular';
  12. $opts['list_id'] = $listId;
  13. $opts['subject'] = 'hello thar!';
  14. $opts['from_email'] = $my_email;
  15. $opts['from_name'] = 'My Name';
  16.  
  17. $opts['tracking']=array('opens' => true, 'html_clicks' => true,
  18. 'text_clicks' => false);
  19.  
  20. $opts['authenticate'] = false;
  21. $opts['analytics'] = array('google'=>'atphga');
  22. $opts['title'] = 'My 123 Campaign';
  23.  
  24. $content = array ('html'=>'something *|UNSUB|* message',
  25. 'text' => 'text text text *|UNSUB|*');
  26.  
  27. $seg = array();
  28.  
  29. $seg['match'] = 'any';
  30. $seg['conditions'][] = array('field'=>'fname', 'op'=>'like', 'value'=>'bob');
  31.  
  32. $result = $client->campaignCreate($apikey, $type, $opts, $content, $seg);
  33. echo "SUCCESS! \n";
  34. echo "New Campaign Id: ".$result."\n";
  35.  
  36. } catch (XML_RPC2_FaultException $e){
  37. echo "ERROR!!!!\n";
  38. echo $e->getFaultCode()." : ".$e->getFaultString()."\n";
  39. }
  40.  
  41. ?>
  42.  

[3] xml-rpc_campaignCreateABSplit.php

  1. <?php
  2. /**
  3. This Example shows how create an A/B Split campaign using XML-RPC.
  4. Note that we are using the PEAR XML-RPC client and recommend others do as well.
  5. **/
  6. require_once 'XML/RPC2/Client.php';
  7. require_once 'inc/config.inc.php';
  8. try {
  9. $client = XML_RPC2_Client::create($apiUrl);
  10.  
  11. $opts['list_id'] = $listId;
  12. $opts['subject'] = 'hello thar!';
  13. $opts['from_email'] = $my_email;
  14. $opts['from_name'] = 'My Name';
  15.  
  16. $opts['tracking']=array('opens' => true, 'html_clicks' => true,
  17. 'text_clicks' => false);
  18.  
  19. $opts['authenticate'] = false;
  20. $opts['analytics'] = array('google'=>'atphga');
  21. $opts['title'] = 'My 123 Campaign';
  22.  
  23. $content = array ('html'=>'something *|UNSUB|* message',
  24. 'text' => 'text text text *|UNSUB|*');
  25. //no segmentation on this one.
  26. $seg = array();
  27.  
  28. $type = "absplit";
  29. $type_opts = array();
  30. $type_opts['split_test'] = 'schedule';
  31. $type_opts['pick_winner'] = 'manual';
  32.  
  33. $type_opts['from_name_a'] = 'Wahoo McDaniels';
  34. $type_opts['from_email_a'] = 'wahoo@example.org';
  35. $type_opts['from_name_b'] = 'Yahoo McDonald';
  36. $type_opts['from_email_b'] = 'yahoo@example.org';
  37.  
  38. $result = $client->campaignCreate($apikey, $type, $opts, $content, $seg, $type_opts);
  39. echo "SUCCESS! \n";
  40. echo "New Campaign Id: ".$result."\n";
  41.  
  42. } catch (XML_RPC2_FaultException $e){
  43. echo "ERROR!!!!\n";
  44. echo $e->getFaultCode()." : ".$e->getFaultString()."\n";
  45. }
  46.  
  47. ?>
  48.  

[4] xml-rpc_campaignCreateRss.php

  1. <?php
  2. /**
  3. This Example shows how create a RSS campaign using XML-RPC.
  4. Note that we are using the PEAR XML-RPC client and recommend others do as well.
  5. **/
  6. require_once 'XML/RPC2/Client.php';
  7. require_once 'inc/config.inc.php';
  8. try {
  9. $client = XML_RPC2_Client::create($apiUrl);
  10.  
  11. $opts['list_id'] = $listId;
  12. $opts['subject'] = 'hello thar!';
  13. $opts['from_email'] = $my_email;
  14. $opts['from_name'] = 'My Name';
  15.  
  16. $opts['tracking']=array('opens' => true, 'html_clicks' => true,
  17. 'text_clicks' => false);
  18.  
  19. $opts['authenticate'] = false;
  20. $opts['analytics'] = array('google'=>'atphga');
  21. $opts['title'] = 'My 123 Campaign';
  22.  
  23. $content = array ('html'=>'something *|UNSUB|* message',
  24. 'text' => 'text text text *|UNSUB|*');
  25. //no segmentation on this one.
  26. $seg = array();
  27.  
  28. $type = 'rss';
  29. $type_opts = array();
  30. $type_opts['url'] = 'http://mailchimp.com/blog/rss';
  31.  
  32. $result = $client->campaignCreate($apikey, $type, $opts, $content, $seg, $type_opts);
  33. echo "SUCCESS! \n";
  34. echo "New Campaign Id: ".$result."\n";
  35.  
  36. } catch (XML_RPC2_FaultException $e){
  37. echo "ERROR!!!!\n";
  38. echo $e->getFaultCode()." : ".$e->getFaultString()."\n";
  39. }
  40.  
  41. ?>
  42.