Interface Inx_Api_Subscription_SubscriptionManager

Description

If the subscription feature is enabled for a standard list, the Inx_Api_Subscription_SubscriptionManager can be used to subscribe and unsubscribe recipients and to retrieve log entries concerning subscription.

If the subscription feature is enabled for a standard list, the Inx_Api_Subscription_SubscriptionManager can be used to subscribe and unsubscribe recipients and to retrieve log entries concerning subscription. The behaviour is the same as if a recipient subscribes to a list via a web frontend. For example, if double opt in is configured, calling processSubscription() will start the normal double opt in subscription process.

The subscription process requires some information:

  • The source identifier: A string which describes the source of the subscription (e.g. the name of the landing page)
  • The remote address: The IP address of the subscriber
  • The list context: The mailing list to which the recipient shall be subscribed
  • The email address: The email address of the subscriber
  • An attribute map: An associative array of key-value pairs used to specify certain recipient attribute values

The following snippet shows how to subscribe the recipient with the email address name@company.com, the last name Smith, the birthday 1994-10-25 and two children to the specified list, using the specified remote address and Hompage(german) as source:

 $aAttributes = array(
 	"Lastname" => "Smith",
  "Birthday" => "2004-05-06",
  "Children" => 2
 );

 $oSubscriptionManager = $oSession->getSubscriptionManager();
 $iResult = $oSubscriptionManager->processSubscription( "Homepage(german)", $sRemoteAddr, $oListContext,
 		"name@company.com", $aAttributes );

The unsubscription of recipients works pretty much the same. There is only one additional parameter: the mailing reference. This string identifies the mailing which contains the link used to unsubscribe the recipient. However, the mailing reference is only known if the link used for the unsubscription is known. This is the case for unsubscription JSPs but not for common API usage. In most cases the unsubscription of a recipient is accomplished using the Inx_Api_Recipient_RecipientRowSet or the Inx_Api_Recipient_BatchChannel.

The following snippet shows how to unsubscribe the recipient with the email address name@company.com from the specified list, using the specified remote address and mailing reference and Homepage(german) as source:

 $oSubscriptionManager = $oSession->getSubscriptionManager();
 $iResult = $oSubscriptionManager->processUnsubscription( "Homepage(german)", $sRemoteAddr, $oListContext, "name@company.com", $sMailingRef, null );

The result is either PROCESS_ACTIVATION_SUCCESSFULLY if the subscription or unsubscription succeeded, or PROCESS_ACTIVATION_FAILED_ADDRESS_ILLEGAL if the address is not conform to the RFC standard.

In most circumstances, you would add the recipient to the system list with all his profile data prior to calling the SubscriptionManager. For an example on how to add recipients to the system list, see the Inx_Api_Recipient_RecipientContext documentation.

The Inx_Api_Subscription_SubscriptionManager may also be used to retrieve log entries concerning subscription. For example you can retrieve all log entries associated with the subscription and unsubscription of a specific list in the last month. The following snippet shows how to do this and prints out some of the information:

 // create start date
 $sOneMonthAgo = date('c', strtotime("-1 month"));

 // create recipient context and attributes to query
 $oRecipientContext = $oSession->createRecipientContext();
 $oRecipientMetaData = $oRecipientContext->getMetaData();
 $oAttribute_email = $oRecipientMetaData->getEmailAttribute();
 $oAttribute_lastname = $oRecipientMetaData->getUserAttribute( "Lastname" );
 $aAttributes = array( $oAttribute_email, $oAttribute_lastname );

 $oSubscriptionManager = $oSession->getSubscriptionManager();
 $oSubscriptionLogEntryRowSet = $oSubscriptionManager->getLogEntriesAfterAndList( $oListContext, $sOneMonthAgo, $oRecipientContext, $aAttributes );

 while( $oSubscriptionLogEntryRowSet->next() )
 {
 	echo "Log message: ".$oSubscriptionLogEntryRowSet->getLogMessage()."<br>";
 	echo "Log date: ".$oSubscriptionLogEntryRowSet->getEntryDatetime()."<br>";
 	echo "Email address: ".$oSubscriptionLogEntryRowSet->getString( $oAttribute_email )."<br>";
 	echo "Lastname: ".$oSubscriptionLogEntryRowSet->getString( $oAttribute_lastname )."<br><br>";
 }
For more information on this topic, see the Inx_Api_Subscruption_SubscriptionLogEntryRowSet documentation.

Located in /Api/Subscription/SubscriptionManager.php (line 103)


	
			
Class Constant Summary
Method Summary
int processSubscription ([string $sSourceIdentifier = null], [string $sRemoteAddress = null], Inx_Api_List_StandardListContext $oListContext, string $sEmailAddress, [associative $aAttrKeyValuePairs = array()])
the processUnsubscription ([string $sSourceIdentifier = null], [string $sRemoteAddress = null], Inx_Api_List_StandardListContext $ListContext, string $sEmailAddress, [int $iMailingId = 0])
int processUnsubscription3 (string $sSourceIdentifier, string $sRemoteAddress, Inx_Api_List_StandardListContext $oListContext, string $sEmailAddress, int $iMailingId, [array $aAttrKeyValuePairs = null])
the processUnsubscription4 (string $sSourceIdentifier, string $sRemoteAddress, Inx_Api_List_StandardListContext $oListContext, string $sEmailAddress, string $sMailingRef, [array $aAttrKeyValuePairs = null])
Methods
getAllLogEntries (line 237)

Returns an Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries.

Returns an Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries.

  • return: a SubscriptionLogEntryRowSet containing all existing (un)subscription log entries.
  • throws: Inx_Api_NullPointerException if no Inx_Api_Recipient_RecipientContext is provided.
  • access: public
  • Inx_Api_Recipient_RecipientContext $rc: the RecipientContext used to fetch the attribute data.
  • array $attrs: an array of recipient attributes (Inx_Api_Recipient_Attribute) which are fetched for later retrieval; may be null.
getLogEntriesAfter (line 337)

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries after a given date.

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries after a given date.

  • return: a SubscriptionLogEntryRowSet containing all existing un/subscription log entries after a given date.
  • throws: Inx_Api_NullPointerException if no Inx_Api_Recipient_RecipientContext is provided.
  • access: public
Inx_Api_Subscription_SubscriptionLogEntryRowSet getLogEntriesAfter (string $after, Inx_Api_Recipient_RecipientContext $rc, array $attrs)
  • string $after: all log entries after this date will be fetched. The date has to be passed as ISO8601 formatted datetime string.
  • Inx_Api_Recipient_RecipientContext $rc: the RecipientContext used to fetch the attribute data.
  • array $attrs: an array of recipient attributes (Inx_Api_Recipient_Attribute) which are fetched for later retrieval; may be null.
getLogEntriesAfterAndList (line 286)

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries for a given list and after a given date.

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries for a given list and after a given date.

  • return: a SubscriptionLogEntryRowSet containing all existing (un)subscription log entries for a given list and after a given date.
  • throws: Inx_Api_NullPointerException if no Inx_Api_Recipient_RecipientContext is provided.
  • access: public
Inx_Api_Subscription_SubscriptionLogEntryRowSet getLogEntriesAfterAndList (Inx_Api_List_ListContext $lc, string $after, Inx_Api_Recipient_RecipientContext $rc, array $attrs)
  • Inx_Api_List_ListContext $lc: the list for which the (un)subscription log entries shall be fetched.
  • string $after: all log entries after this date will be fetched. The date has to be passed as ISO8601 formatted datetime string.
  • Inx_Api_Recipient_RecipientContext $rc: the RecipientContext used to fetch the attribute data.
  • array $attrs: an array of recipient attributes (Inx_Api_Recipient_Attribute) which are fetched for later retrieval; may be null.
getLogEntriesBefore (line 321)

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries before a given date.

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries before a given date.

  • return: a SubscriptionLogEntryRowSet containing all existing un/subscription log entries before a given date.
  • throws: Inx_Api_NullPointerException if no Inx_Api_Recipient_RecipientContext is provided.
  • access: public
Inx_Api_Subscription_SubscriptionLogEntryRowSet getLogEntriesBefore (string $before, Inx_Api_Recipient_RecipientContext $rc, array $attrs)
  • string $before: all log entries before this date will be fetched. The date has to be passed as ISO8601 formatted datetime string.
  • Inx_Api_Recipient_RecipientContext $rc: the RecipientContext used to fetch the attribute data.
  • array $attrs: an array of recipient attributes (Inx_Api_Recipient_Attribute) which are fetched for later retrieval; may be null.
getLogEntriesBeforeAndList (line 269)

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries for a given list and before a given date.

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries for a given list and before a given date.

  • return: a SubscriptionLogEntryRowSet containing all existing (un)subscription log entries for a given list and before a given date.
  • throws: Inx_Api_NullPointerException if no Inx_Api_Recipient_RecipientContext is provided.
  • access: public
Inx_Api_Subscription_SubscriptionLogEntryRowSet getLogEntriesBeforeAndList (Inx_Api_List_ListContext $lc, string $before, Inx_Api_Recipient_RecipientContext $rc, array $attrs)
  • Inx_Api_List_ListContext $lc: the list for which the (un)subscription log entries shall be fetched.
  • string $before: all log entries before this date will be fetched. The date has to be passed as ISO8601 formatted datetime string.
  • Inx_Api_Recipient_RecipientContext $rc: the RecipientContext used to fetch the attribute data.
  • array $attrs: an array of recipient attributes (Inx_Api_Recipient_Attribute) which are fetched for later retrieval; may be null.
getLogEntriesBetween (line 355)

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries between given dates.

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries between given dates.

  • return: a SubscriptionLogEntryRowSet containing all existing (un)subscription log entries between given dates.
  • throws: Inx_Api_NullPointerException if no Inx_Api_Recipient_RecipientContext is provided.
  • access: public
Inx_Api_Subscription_SubscriptionLogEntryRowSet getLogEntriesBetween (string $start, string $end, Inx_Api_Recipient_RecipientContext $rc, array $attrs)
  • string $start: the start date for the search. The date has to be passed as ISO8601 formatted datetime string.
  • string $end: the end date for the search. The date has to be passed as ISO8601 formatted datetime string.
  • Inx_Api_Recipient_RecipientContext $rc: the RecipientContext used to fetch the attribute data.
  • array $attrs: an array of recipient attributes (Inx_Api_Recipient_Attribute) which are fetched for later retrieval; may be null.
getLogEntriesBetweenAndList (line 305)

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries for a given list and between the given dates.

Returns a Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries for a given list and between the given dates.

  • return: a SubscriptionLogEntryRowSet containing all existing (un)subscription log entries for a given list and between the given dates.
  • throws: Inx_Api_NullPointerException if no Inx_Api_Recipient_RecipientContext is provided.
  • access: public
Inx_Api_Subscription_SubscriptionLogEntryRowSet getLogEntriesBetweenAndList (Inx_Api_List_ListContext $lc, string $start, string $end, Inx_Api_Recipient_RecipientContext $rc, array $attrs)
  • Inx_Api_List_ListContext $lc: the list for which the (un)subscription log entries shall be fetched.
  • string $start: the start date for the search. The date has to be passed as ISO8601 formatted datetime string.
  • string $end: the end date for the search. The date has to be passed as ISO8601 formatted datetime string.
  • Inx_Api_Recipient_RecipientContext $rc: the RecipientContext used to fetch the attribute data.
  • array $attrs: an array of recipient attributes (Inx_Api_Recipient_Attribute) which are fetched for later retrieval; may be null.
getLogEntriesForList (line 252)

Returns an Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries for a given list.

Returns an Inx_Api_Subsciption_SubscriptionLogEntryRowSet containing all existing (un)subscription log entries for a given list.

  • return: a SubscriptionLogEntryRowSet containing all existing (un)subscription log entries.
  • throws: Inx_Api_NullPointerException if no Inx_Api_Recipient_RecipientContext is provided.
  • access: public
  • Inx_Api_List_ListContext $lc: the list for which the (un)subscription log entries shall be fetched.
  • Inx_Api_Recipient_RecipientContext $rc: the RecipientContext used to fetch the attribute data.
  • array $attrs: an array of recipient attributes (Inx_Api_Recipient_Attribute) which are fetched for later retrieval; may be null.
processSubscription (line 141)

Activates the subscription process for the specified email address and sets the attribute values specified in the given associative array.

Activates the subscription process for the specified email address and sets the attribute values specified in the given associative array.

  • return: the state of the process activation. May be one of:
    • PROCESS_ACTIVATION_SUCCESSFULLY: the process was successfully activated
    • PROCESS_ACTIVATION_FAILED_ADDRESS_ILLEGAL: the provided email address is not conform to the RFC standard.
  • since: API 1.0.2
  • throws: Inx_Api_FeatureNotAvailableException if the subscription feature is not enabled.
  • throws: Inx_Api_SecurityException if the session user doesn't have the following permission: Inx_Api_UserRights::SUBSCRIPTION_FEATURE_USE
  • access: public
int processSubscription ([string $sSourceIdentifier = null], [string $sRemoteAddress = null], Inx_Api_List_StandardListContext $oListContext, string $sEmailAddress, [associative $aAttrKeyValuePairs = array()])
  • string $sSourceIdentifier: the source identifier used for reports (e.g. the name of the landing page).
  • string $sRemoteAddress: the remote IP address of the subscriber.
  • Inx_Api_List_StandardListContext $oListContext: the list to which the recipient shall be subscribed.
  • string $sEmailAddress: the email address of the recipient.
  • associative $aAttrKeyValuePairs: array $aAttrKeyValuePairs a map of attribute key/value-pairs which will be set for the recipient; may be null or ommitted.
processUnsubscription (line 167)

Activates the unsubscription process for the specified email address and mailing id.

Activates the unsubscription process for the specified email address and mailing id. The mailing id specifies the mailing, which contains the unsubscription link used to unsubscribe the recipient.

  • return: state of the process activation. May be one of:
    • PROCESS_ACTIVATION_SUCCESSFULLY: the process was successfully activated
    • PROCESS_ACTIVATION_FAILED_ADDRESS_ILLEGAL: the provided email address is not conform to the RFC standard.
  • deprecated: use
  • throws: Inx_Api_SecurityException if the session user doesn't have the following permission: Inx_Api_UserRights::SUBSCRIPTION_FEATURE_USE
  • since: API 1.5.0
  • throws: FeatureNotAvailableException Inx_Api_FeatureNotAvailableException if the subscription feature is not enabled.
  • access: public
the processUnsubscription ([string $sSourceIdentifier = null], [string $sRemoteAddress = null], Inx_Api_List_StandardListContext $ListContext, string $sEmailAddress, [int $iMailingId = 0])
  • string $sSourceIdentifier: the source identifier used for reports (e.g. the name of the landing page).
  • string $sRemoteAddress: the remote IP address of the unsubscriber.
  • Inx_Api_List_StandardListContext $ListContext: the list from which the recipient shall be unsubscribed.
  • string $sEmailAddress: the email address of the recipient.
  • int $iMailingId: the id of the mailing which contains the used unsubscription link.
processUnsubscription3 (line 196)

Activates the unsubscription process for the specified email address and mailing id and sets the attribute values specified in the given associative array.

Activates the unsubscription process for the specified email address and mailing id and sets the attribute values specified in the given associative array. The mailing id specifies the mailing, which contains the unsubscription link used to unsubscribe the recipient.

  • return: the state of the process activation. May be one of:
    • PROCESS_ACTIVATION_SUCCESSFULLY: the process was successfully activated
    • PROCESS_ACTIVATION_FAILED_ADDRESS_ILLEGAL: the provided email address is not conform to the RFC standard.
  • deprecated: use
  • throws: Inx_Api_SecurityException if the session user doesn't have the following permission: Inx_Api_UserRights::SUBSCRIPTION_FEATURE_USE
  • since: API 1.9.0
  • throws: Inx_Api_FeatureNotAvailableException if the subscription feature is not enabled.
  • access: public
int processUnsubscription3 (string $sSourceIdentifier, string $sRemoteAddress, Inx_Api_List_StandardListContext $oListContext, string $sEmailAddress, int $iMailingId, [array $aAttrKeyValuePairs = null])
  • string $sSourceIdentifier: the source identifier used for reports (e.g. the name of the landing page).
  • string $sRemoteAddress: the remote IP address of the unsubscriber.
  • Inx_Api_List_StandardListContext $oListContext: the list from which the recipient shall be unsubscribed.
  • string $sEmailAddress: the email address of the recipient.
  • int $iMailingId: the id of the mailing which contains the used unsubscription link.
  • array $aAttrKeyValuePairs: an associative array of attribute key/value-pairs which will be set for the recipient; may be null or ommitted.
processUnsubscription4 (line 223)

Activates the unsubscription process for the specified email address and mailing reference and sets the attribute values specified in the given associative array.

Activates the unsubscription process for the specified email address and mailing reference and sets the attribute values specified in the given associative array. The mailing reference specifies the mailing, which contains the unsubscription link used to unsubscribe the recipient.

  • return: state of the process activation. May be one of:
    • PROCESS_ACTIVATION_SUCCESSFULLY: the process was successfully activated
    • PROCESS_ACTIVATION_FAILED_ADDRESS_ILLEGAL: the provided email address is not conform to the RFC standard.
  • since: API 1.9.0
  • throws: Inx_Api_FeatureNotAvailableException if the subscription feature is not enabled.
  • throws: Inx_Api_SecurityException if the session user doesn't have the following permission: Inx_Api_UserRights::SUBSCRIPTION_FEATURE_USE
  • access: public
the processUnsubscription4 (string $sSourceIdentifier, string $sRemoteAddress, Inx_Api_List_StandardListContext $oListContext, string $sEmailAddress, string $sMailingRef, [array $aAttrKeyValuePairs = null])
  • string $sSourceIdentifier: the source identifier used for reports (e.g. the name of the landing page).
  • string $sRemoteAddress: the remote IP address of the unsubscriber.
  • Inx_Api_List_ListContext $oListContext: the list from which the recipient shall be unsubscribed.
  • string $sEmailAddress: the email address of the recipient.
  • string $sMailingRef: the mailing reference of the mailing which contains the used unsubscription link.
  • array $aAttrKeyValuePairs: an associative array of attribute key/value-pairs which will be set for the recipient; may be null or ommitted.
Class Constants
PROCESS_ACTIVATION_FAILED_ADDRESS_ILLEGAL = 3002 (line 117)

Subscription or Unsubscription process activation has failed, the address is not conform to the RFC standard.

Subscription or Unsubscription process activation has failed, the address is not conform to the RFC standard.

PROCESS_ACTIVATION_SUCCESSFULLY = 3000 (line 110)

Subscription or Unsubscription process has been successfully activated.

Subscription or Unsubscription process has been successfully activated.

Documentation generated on Thu, 17 Sep 2015 14:27:31 +0200 by phpDocumentor 1.3.2