Declared in CSAPI+Lists.h

Overview

List-related APIs. See CSAPI for documentation of the other API categories.

Tasks

Other Methods

Custom Fields

Web Hooks

Instance Methods

activateWebhookWithListID:webhookID:completionHandler:errorHandler:

Activate a webhook associated with a list

- (void)activateWebhookWithListID:(NSString *)listID webhookID:(NSString *)webhookID completionHandler:(void ( ^ ) ( void ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list with which the webhook you want to activate is associated

webhookID

The ID of the webhook to be activated

completionHandler

Completion callback

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#activating_a_webhook

Declared In

CSAPI+Lists.h

createCustomFieldWithListID:customField:completionHandler:errorHandler:

Create a new custom field for a given list into which custom subscriber data can be added

- (void)createCustomFieldWithListID:(NSString *)listID customField:(CSCustomField *)customField completionHandler:(void ( ^ ) ( NSString *customFieldKey ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want to create the custom field on

customField

A CSCustomField representing the field you’d like to create. See [CSCustomField customFieldWithName:dataType:options:] and [CSCustomField customFieldWithName:dataType:].

completionHandler

Completion callback, with the key of the newly created custom field as the first and only argument

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#creating_a_custom_field

Declared In

CSAPI+Lists.h

createListWithClientID:title:unsubscribePage:unsubscribeSetting:confirmationSuccessPage:shouldConfirmOptIn:completionHandler:errorHandler:

Create a new list into which subscribers can be added or imported

- (void)createListWithClientID:(NSString *)clientID title:(NSString *)title unsubscribePage:(NSString *)unsubscribePage unsubscribeSetting:(NSString *)unsubscribeSetting confirmationSuccessPage:(NSString *)confirmationSuccessPage shouldConfirmOptIn:(BOOL)shouldConfirmOptIn completionHandler:(void ( ^ ) ( NSString *listID ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

clientID

The ID of the client for whom the list should be created

title

The title of the new list. Must be unique.

unsubscribePage

URL for the unsubscribe page

unsubscribeSetting

The unsubscribe setting for the list – must be one of:

  • AllClientLists
  • OnlyThisList

If set to AllClientLists, when someone unsubscribes from this list they will also be unsubscribed from all the client’s lists (recommended). If set to OnlyThisList, when someone unsubscribes from this list they will only be unsubscribed from this list.

Setting OnlyThisList will result in this list not using the suppression list, meaning that if a subscriber on this list is added to the suppression list they will not be unsubscribed from this list.

confirmationSuccessPage

URL for the subscription confirmation page

shouldConfirmOptIn

Whether or not subscriptions need to be confirmed

completionHandler

Completion callback, with the ID of the successfully created list

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#creating_a_list

Declared In

CSAPI+Lists.h

createWebhookWithListID:events:URLString:payloadFormat:completionHandler:errorHandler:

Create a new webhook for the provided list

- (void)createWebhookWithListID:(NSString *)listID events:(NSArray *)events URLString:(NSString *)URLString payloadFormat:(NSString *)payloadFormat completionHandler:(void ( ^ ) ( NSString *webhookID ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list for which the webhook should be created

events

The events you would like to trigger a call to your webhook. Valid events are Subscribe, Deactivate and Update.

URLString

The URL endpoint you’d like called when an event occurs

payloadFormat

The payload format you’d like to receive at the URLString endpoint. Valid payload formats are json and xml.

completionHandler

Completion callback, with the ID of the newly created webhook as the first and only argument

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#creating_a_webhook

Declared In

CSAPI+Lists.h

deactivateWebhookWithListID:webhookID:completionHandler:errorHandler:

Deactivate a webhook associated with a list

- (void)deactivateWebhookWithListID:(NSString *)listID webhookID:(NSString *)webhookID completionHandler:(void ( ^ ) ( void ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list with which the webhook you want to deactivate is associated

webhookID

The ID of the webhook to be deactivated

completionHandler

Completion callback

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#deactivating_a_webhook

Declared In

CSAPI+Lists.h

deleteCustomFieldWithListID:customFieldKey:completionHandler:errorHandler:

Deletes a specific custom field from a list

- (void)deleteCustomFieldWithListID:(NSString *)listID customFieldKey:(NSString *)fieldKey completionHandler:(void ( ^ ) ( void ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list containing the custom field you’d like to delete

fieldKey

The custom field key. You can get the key of a custom field by calling getCustomFieldsWithListID:completionHandler:errorHandler:.

completionHandler

Completion callback

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#deleting_a_custom_field

Declared In

CSAPI+Lists.h

deleteListWithID:completionHandler:errorHandler:

Deletes a subscriber list from your account

- (void)deleteListWithID:(NSString *)listID completionHandler:(void ( ^ ) ( void ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want to delete

completionHandler

Completion callback

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#deleting_a_list

Declared In

CSAPI+Lists.h

deleteWebhookWithListID:webhookID:completionHandler:errorHandler:

Delete a specific webhook associated with a list

- (void)deleteWebhookWithListID:(NSString *)listID webhookID:(NSString *)webhookID completionHandler:(void ( ^ ) ( void ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list from which the webhook should be deleted

webhookID

The ID of the webhook you’d like to delete

completionHandler

Completion callback

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#deleting_a_webhook

Declared In

CSAPI+Lists.h

getActiveSubscribersWithListID:date:page:pageSize:orderField:ascending:completionHandler:errorHandler:

Get a paged result representing all the active subscribers for a given list

- (void)getActiveSubscribersWithListID:(NSString *)listID date:(NSDate *)date page:(NSUInteger)page pageSize:(NSUInteger)pageSize orderField:(NSString *)orderField ascending:(BOOL)ascending completionHandler:(void ( ^ ) ( CSPaginatedResult *paginatedResult ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want the active subscribers for

date

Subscribers which became active on or after the date specified will be returned

page

The page to retrieve

pageSize

The number of subscribers to retrieve per page. Values accepted are between 10 and 1000.

orderField

The subscriber field to order the list by. Values accepted are email, name or date.

ascending

Whether to sort the list (see orderField) in ascending order

completionHandler

Completion callback, with a CSPaginatedResult as the first and only argument. Items in the result list are CSSubscriber.

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#active_subscribers

Declared In

CSAPI+Lists.h

getBouncedSubscribersWithListID:date:page:pageSize:orderField:ascending:completionHandler:errorHandler:

Get a paged result representing all the bounced subscribers for a given list

- (void)getBouncedSubscribersWithListID:(NSString *)listID date:(NSDate *)date page:(NSUInteger)page pageSize:(NSUInteger)pageSize orderField:(NSString *)orderField ascending:(BOOL)ascending completionHandler:(void ( ^ ) ( CSPaginatedResult *paginatedResult ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want the bounced subscribers for

date

Subscribers which bounced on or after the date specified will be returned

page

The page to retrieve

pageSize

The number of subscribers to retrieve per page. Values accepted are between 10 and 1000.

orderField

The subscriber field to order the list by. Values accepted are email, name or date.

ascending

Whether to sort the list (see orderField) in ascending order

completionHandler

Completion callback, with a CSPaginatedResult as the first and only argument. Items in the result list are CSSubscriber.

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#bounced_subscribers

Declared In

CSAPI+Lists.h

getCustomFieldsWithListID:completionHandler:errorHandler:

Get all the custom fields for a given list in your account

- (void)getCustomFieldsWithListID:(NSString *)listID completionHandler:(void ( ^ ) ( NSArray *customFields ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want the custom fields for

completionHandler

Completion callback, with an array of CSCustomField objects as the first and only argument

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#list_custom_fields

Declared In

CSAPI+Lists.h

getDeletedSubscribersWithListID:date:page:pageSize:orderField:ascending:completionHandler:errorHandler:

Get a paged result representing all the deleted subscribers for a given list

- (void)getDeletedSubscribersWithListID:(NSString *)listID date:(NSDate *)date page:(NSUInteger)page pageSize:(NSUInteger)pageSize orderField:(NSString *)orderField ascending:(BOOL)ascending completionHandler:(void ( ^ ) ( CSPaginatedResult *paginatedResult ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want the deleted subscribers for

date

Subscribers which were deleted on or after the date specified will be returned

page

The page to retrieve

pageSize

The number of subscribers to retrieve per page. Values accepted are between 10 and 1000.

orderField

The subscriber field to order the list by. Values accepted are email, name or date.

ascending

Whether to sort the list (see orderField) in ascending order

completionHandler

Completion callback, with a CSPaginatedResult as the first and only argument. Items in the result list are CSSubscriber.

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#deleted_subscribers

Declared In

CSAPI+Lists.h

getListDetailsWithListID:completionHandler:errorHandler:

Get a basic summary for a list in your account

- (void)getListDetailsWithListID:(NSString *)listID completionHandler:(void ( ^ ) ( CSList *list ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want the details for

completionHandler

Completion callback, with a CSList as the only argument.

errorHandler

Error callback

Declared In

CSAPI+Lists.h

getListSegmentsWithListID:completionHandler:errorHandler:

Get all list segments for a list in your account

- (void)getListSegmentsWithListID:(NSString *)listID completionHandler:(void ( ^ ) ( NSArray *listSegments ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want the segments for

completionHandler

Completion callback, with an array of CSSegment objects as the only argument.

errorHandler

Error callback

Declared In

CSAPI+Lists.h

getListStatisticsWithListID:completionHandler:errorHandler:

Get comprehensive summary statistics for a list in your account

- (void)getListStatisticsWithListID:(NSString *)listID completionHandler:(void ( ^ ) ( NSDictionary *listStatistics ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want the statistics for

completionHandler

Completion callback, with a dictionary of statistics as the only argument. The statistics dictionary is in the following format:

{ “TotalActiveSubscribers”: 6, “NewActiveSubscribersToday”: 0, “NewActiveSubscribersYesterday”: 8, “NewActiveSubscribersThisWeek”: 8, “NewActiveSubscribersThisMonth”: 8, “NewActiveSubscribersThisYear”: 8, “TotalUnsubscribes”: 2, “UnsubscribesToday”: 0, “UnsubscribesYesterday”: 2, “UnsubscribesThisWeek”: 2, “UnsubscribesThisMonth”: 2, “UnsubscribesThisYear”: 2, “TotalDeleted”: 0, “DeletedToday”: 0, “DeletedYesterday”: 0, “DeletedThisWeek”: 0, “DeletedThisMonth”: 0, “DeletedThisYear”: 0, “TotalBounces”: 0, “BouncesToday”: 0, “BouncesYesterday”: 0, “BouncesThisWeek”: 0, “BouncesThisMonth”: 0, “BouncesThisYear”: 0 }

errorHandler

Error callback

Declared In

CSAPI+Lists.h

getUnconfirmedSubscribersWithListID:date:page:pageSize:orderField:ascending:completionHandler:errorHandler:

Get a paged result representing all the unconfirmed subscribers for a given list (those subscribers who have subscribed to a confirmed-opt-in list, but have not confirmed their subscription).

- (void)getUnconfirmedSubscribersWithListID:(NSString *)listID date:(NSDate *)date page:(NSUInteger)page pageSize:(NSUInteger)pageSize orderField:(NSString *)orderField ascending:(BOOL)ascending completionHandler:(void ( ^ ) ( CSPaginatedResult *paginatedResult ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want the unconfirmed subscribers for

date

Subscribers who subscribed on or after the date specified will be returned

page

The page to retrieve

pageSize

The number of subscribers to retrieve per page. Values accepted are between 10 and 1000.

orderField

The subscriber field to order the list by. Values accepted are email, name or date.

ascending

Whether to sort the list (see orderField) in ascending order

completionHandler

Completion callback, with a CSPaginatedResult as the first and only argument. Items in the result list are CSSubscriber.

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#unconfirmed_subscribers

Declared In

CSAPI+Lists.h

getUnsubscribedSubscribersWithListID:date:page:pageSize:orderField:ascending:completionHandler:errorHandler:

Get a paged result representing all the unsubscribed subscribers for a given list

- (void)getUnsubscribedSubscribersWithListID:(NSString *)listID date:(NSDate *)date page:(NSUInteger)page pageSize:(NSUInteger)pageSize orderField:(NSString *)orderField ascending:(BOOL)ascending completionHandler:(void ( ^ ) ( CSPaginatedResult *paginatedResult ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want the unsubscribed subscribers for

date

Subscribers which unsubscribed on or after the date specified will be returned

page

The page to retrieve

pageSize

The number of subscribers to retrieve per page. Values accepted are between 10 and 1000.

orderField

The subscriber field to order the list by. Values accepted are email, name or date.

ascending

Whether to sort the list (see orderField) in ascending order

completionHandler

Completion callback, with a CSPaginatedResult as the first and only argument. Items in the result list are CSSubscriber.

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#unsubscribed_subscribers

Declared In

CSAPI+Lists.h

getWebhooksWithListID:completionHandler:errorHandler:

Get all the webhooks that have been created for a given list

- (void)getWebhooksWithListID:(NSString *)listID completionHandler:(void ( ^ ) ( NSArray *webhooks ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the subscriber list for which webhooks should be retrieved

completionHandler

Completion callback, with an array of CSWebhook objects as the first and only argument

errorHandler

Error callback

Declared In

CSAPI+Lists.h

testWebhookWithListID:webhookID:completionHandler:errorHandler:

Attempt to post a webhook payload to the endpoint specified by a webhook

- (void)testWebhookWithListID:(NSString *)listID webhookID:(NSString *)webhookID completionHandler:(void ( ^ ) ( void ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the subscriber list to which the webhook belongs

webhookID

The ID of the webhook for which the test should be sent

completionHandler

Completion callback

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#testing_a_webhook

Declared In

CSAPI+Lists.h

updateCustomFieldOptionsWithListID:customFieldKey:options:keepExisting:completionHandler:errorHandler:

Update the available options for a multi-select field in a given list

- (void)updateCustomFieldOptionsWithListID:(NSString *)listID customFieldKey:(NSString *)fieldKey options:(NSArray *)options keepExisting:(BOOL)keepExisting completionHandler:(void ( ^ ) ( void ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list containing the custom key you’d like to update

fieldKey

The custom field key. You can get the key of a custom field by calling getCustomFieldsWithListID:completionHandler:errorHandler:.

options

An array of strings enumerating the available options

keepExisting

Whether or not to keep the existing options. If NO, existing options are replaced

completionHandler

Completion callback

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#updating_custom_field_options

Declared In

CSAPI+Lists.h

updateCustomFieldWithListID:customField:completionHandler:errorHandler:

Update a custom field, setting the name and whether or not it is visible in the subscriber preference center. To update the options for the custom field you should use [CSAPI (Lists) updateCustomFieldOptionsWithListID:fieldKey:options:keepExisting:completionHandler:errorHandler:].

- (void)updateCustomFieldWithListID:(NSString *)listID customField:(CSCustomField *)customField completionHandler:(void ( ^ ) ( NSString *customFieldKey ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list to which the custom field belongs

customField

A CSCustomField representing the field you’d like to update. See [CSCustomField customFieldWithName:dataType:options:] and [CSCustomField customFieldWithName:dataType:].

completionHandler

Completion callback, with the key of the updated custom field as the first and only argument

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#updating_a_custom_field

Declared In

CSAPI+Lists.h

updateListWithListID:title:unsubscribePage:unsubscribeSetting:confirmationSuccessPage:shouldConfirmOptIn:addUnsubscribesToSuppList:scrubActiveWithSuppList:completionHandler:errorHandler:

Update the basic settings for any list in your account

- (void)updateListWithListID:(NSString *)listID title:(NSString *)title unsubscribePage:(NSString *)unsubscribePage unsubscribeSetting:(NSString *)unsubscribeSetting confirmationSuccessPage:(NSString *)confirmationSuccessPage shouldConfirmOptIn:(BOOL)shouldConfirmOptIn addUnsubscribesToSuppList:(BOOL)addUnsubscribesToSuppList scrubActiveWithSuppList:(BOOL)scrubActiveWithSuppList completionHandler:(void ( ^ ) ( void ))completionHandler errorHandler:(CSAPIErrorHandler)errorHandler

Parameters

listID

The ID of the list you want to update

title

The title of the new list. Must be unique.

unsubscribePage

URL for the unsubscribe page

unsubscribeSetting

The unsubscribe setting for the list – must be one of:

  • AllClientLists
  • OnlyThisList

If set to AllClientLists, when someone unsubscribes from this list they will also be unsubscribed from all the client’s lists (recommended). If set to OnlyThisList, when someone unsubscribes from this list they will only be unsubscribed from this list.

If you specify the value of AllClientLists, you should check that params addUnsubscribesToSuppList and scrubActiveWithSuppList are set appropriately (see param descriptions below).

Setting OnlyThisList will result in this list not using the suppression list, meaning that if a subscriber on this list is added to the suppression list they will not be unsubscribed from this list.

confirmationSuccessPage

URL for the subscription confirmation page

shouldConfirmOptIn

Whether or not subscriptions need to be confirmed

addUnsubscribesToSuppList

If you pass in unsubcribeSetting as AllClientLists, when the value for this param is set to YES, any subscribers who previously unsubscribed from this list will be added to the suppression list.

scrubActiveWithSuppList

If you pass in unsubcribeSetting as AllClientLists, when the value for this param is set to YES, this will scrub all of the active subscribers in this list against the suppression list.

completionHandler

Completion callback

errorHandler

Error callback

Discussion

http://www.campaignmonitor.com/api/lists/#updating_a_list

Declared In

CSAPI+Lists.h