« Back to Documentation Overview

listSubscribe – v1.1

 listSubscribe(string apikey, string id, string email_address, array merge_vars, string email_type, boolean double_optin)

Subscribe the provided email to a list. By default this sends a confirmation email - you will not see new members until the link contained in it is clicked!

Section
List Related
Parameters
apikey a valid API Key for your user account. Get by calling Get by visiting your API dashboard
id the list id to connect to. Get by calling lists()
email_address the email address to subscribe
merge_vars array of merges for the email (FNAME, LNAME, etc.) (see examples below for handling "blank" arrays). Note that a merge field can only hold up to 255 characters. Also, there are 2 "special" keys:
stringINTERESTSSet Interest Groups by passing a field named "INTERESTS" that contains a comma delimited list of Interest Groups to add. Commas in Interest Group names should be escaped with a backslash. ie, "," => "\,"
arrayGROUPINGSSet Interest Groups by Grouping. Each element in this array should be an array containing the "groups" parameter (same restrictions as INTERESTS above) and either an "id" or "name" parameter to specify the Grouping - get from listInterestGroupings()
stringOPTINIPSet the Opt-in IP fields. Abusing this may cause your account to be suspended.
email_type optional - email type preference for the email (html or text, defaults to html)
double_optin optional - flag to control whether a double opt-in confirmation message is sent, defaults to true. Abusing this may cause your account to be suspended.
Returns
boolean true on success, false on failure. When using MCAPI.class.php, the value can be tested and error messages pulled from the MCAPI object (see below)

Examples (2)

download example code

[1] mcapi_listSubscribe.php

  1. <?php
  2. /**
  3. This Example shows how to Subscribe a New Member to a List using the MCAPI.php
  4. class and do some basic error checking.
  5. **/
  6. require_once 'inc/MCAPI.class.php';
  7. require_once 'inc/config.inc.php'; //contains apikey
  8.  
  9. $api = new MCAPI($apikey);
  10.  
  11. /**
  12. Note that if you are not passing merge_vars, you will still need to
  13. pass a "blank" array. That should be either:
  14. $merge_vars = array('');
  15. - or -
  16. $merge_vars = '';
  17.  
  18. Specifically, this will fail:
  19. $merge_vars = array();
  20.  
  21. Or pass the proper data as below...
  22. */
  23. $merge_vars = array('FNAME'=>'Test', 'LNAME'=>'Account',
  24. 'INTERESTS'=>'');
  25. // By default this sends a confirmation email - you will not see new members
  26. // until the link contained in it is clicked!
  27. $retval = $api->listSubscribe( $listId, $my_email, $merge_vars );
  28.  
  29. if ($api->errorCode){
  30. echo "Unable to load listSubscribe()!\n";
  31. echo "\tCode=".$api->errorCode."\n";
  32. echo "\tMsg=".$api->errorMessage."\n";
  33. } else {
  34. echo "Returned: ".$retval."\n";
  35. }
  36.  
  37.  

[2] xml-rpc_listSubscribe.php

  1. <?php
  2. /**
  3. This Example shows how to Subscribe a New Member to a List 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. // Note that the same blank array() restriction for the merge_vars
  12. // does not apply here as XML-RPC will handle it unless you use a null value
  13. $merges = array('FNAME'=>'Test', 'LNAME'=>'Account',
  14. 'INTERESTS'=>'Dogs,Horses');
  15. // By default this sends a confirmation email - you will not see new members
  16. // until the link contained in it is clicked!
  17. $result = $client->listSubscribe($apikey, $listId, $my_email, $merges, 'html', false);
  18. echo "SUCCESS!\n";
  19. echo "Returned: ".$result."\n";
  20. } catch (XML_RPC2_FaultException $e){
  21. echo "ERROR!!!!\n";
  22. echo $e->getFaultCode()." : ".$e->getFaultString()."\n";
  23. }
  24. ?>
  25.