Skip to content

Subscriber Lists

Retrieve List Details

POST /api.php

This endpoint retrieves detailed information about a specific list, including segments, custom fields, subscriber tags, and autoresponders associated with the list.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandList.AssetsYes
ListIDThe unique identifier for the list to retrieve details forYes
bash
curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
      "SessionID": "your-session-id",
      "APIKey": "your-api-key",
      "Command": "List.Assets",
      "ListID": "123"
}'
json
{
  "Success": true,
  "ErrorCode": 0,
  "List": {
    "ListID": "123",
    "ListName": "Sample List",
    "RelOwnerUserID": "456"
    // ... other list details
  },
  "Segments": [
    // ... list of segments
  ],
  "CustomFields": [
    // ... list of custom fields
  ],
  "SubscriberTags": [
    // ... list of subscriber tags
  ],
  "AutoResponders": [
    // ... list of autoresponders
  ]
}
json
{
  "Success": false,
  "ErrorCode": 1,
  "ErrorMessage": "Required field 'ListID' is missing."
}
txt
1: Required field 'ListID' is missing.

Create a New Subscriber List

POST /api.php

This endpoint is used to create a new subscriber list for the user. The list will be associated with the user's account based on their UserID.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandList.Create - The command to create a new subscriber listYes
SubscriberListNameThe name of the new subscriber list to be createdYes
bash
curl -X POST https://example.com/api.php \
-H "Content-Type: application/json" \
-d '{
    "SessionID": "your-session-id",
    "APIKey": "your-api-key",
    "Command": "List.Create",
    "subscriberlistname": "My New List"
}'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "ListID": 12345
}
json
{
  "Success": false,
  "ErrorCode": [
    1
  ],
  "ErrorText": "Required field missing: subscriberlistname"
}
txt
1: Required field missing: subscriberlistname
2: Duplicate list name (Note: This check is currently disabled)
3: User has exceeded the maximum number of subscriber lists

Retrieve Subscriber List

POST /api.php

This endpoint retrieves a specific subscriber list based on the provided list identifier.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandList.GetYes
ListIDThe unique identifier for the list to be retrievedYes
bash
curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{"SessionID": "your-session-id", "APIKey": "your-api-key", "Command": "List.Get", "ListID": "123"}'
json
{
  "Success": true,
  "ErrorCode": 0,
  "List": {
    "ListID": "123",
    "ListName": "My Subscriber List",
    "SubscriberCount": 250,
    "EventListTrackerID": "abc",
    "EventUserTrackerID": "abc",
    "EventTrackerJS": "...",
    "EventTrackerProperties": [],
    "LastEventTrackedAt": "2024-02-21 08:33:47"
    // Other list details...
  }
}
json
{
  "Success": false,
  "ErrorCode": {
    "listid": 1
  }
}
txt
1: The 'ListID' parameter is missing or invalid.

Update Subscriber List

POST /api.php

This endpoint updates the information of an existing subscriber list based on the provided parameters.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandList.UpdateYes
SubscriberListIDThe unique identifier of the subscriber list to updateYes
NameThe new name of the subscriber listNo
SenderNameThe new sender's nameNo
SenderEmailAddressThe new sender's email addressNo
SenderCompanyThe new sender's company nameNo
SenderAddressThe new sender's addressNo
OptInModeThe opt-in mode for the list (Single or Double)No
OptInConfirmationEmailIDThe email ID used for opt-in confirmationNo
OptOutAddToSuppressionListWhether to add opt-outs to the suppression list (Yes or No)No
OptOutAddToGlobalSuppressionListWhether to add opt-outs to the global suppression list (Yes or No)No
HideInSubscriberAreaWhether to hide the list in the subscriber area (true or false)No
SendServiceIntegrationFailedNotificationWhether to send notifications on service integration failure (true or false)No
SendActivityNotificationWhether to send activity notifications (true or false)No
SubscriptionConfirmationPendingPageURLURL for the subscription confirmation pending pageNo
SubscriptionConfirmedPageURLURL for the subscription confirmed pageNo
SubscriptionErrorPageURLURL for the subscription error pageNo
UnsubscriptionConfirmedPageURLURL for the unsubscription confirmed pageNo
UnsubscriptionErrorPageURLURL for the unsubscription error pageNo
ReqByEmailSearchToAddressThe email address to search for email-based requestsNo
ReqByEmailSubscriptionCommandThe command for email-based subscriptionNo
ReqByEmailUnsubscriptionCommandThe command for email-based unsubscriptionNo
SyncStatusThe status of data synchronization (Enabled or Disabled)No
SyncPeriodThe period for data synchronizationNo
SyncSendReportEmailWhether to send a report email after synchronization (Yes or No)No
SyncMySQLHostThe MySQL host for data synchronizationNo
SyncMySQLPortThe MySQL port for data synchronizationNo
SyncMySQLUsernameThe MySQL username for data synchronizationNo
SyncMySQLPasswordThe MySQL password for data synchronizationNo
SyncMySQLDBNameThe MySQL database name for data synchronizationNo
SyncMySQLQueryThe MySQL query for data synchronizationNo
SyncFieldMappingThe field mapping for data synchronizationNo
SyncLastDateTimeThe last date and time of data synchronizationNo
OptOutScopeThe scope of opt-out (This list or All lists)No
OptOutSubscribeToThe list ID to subscribe to on opt-outNo
OptOutUnsubscribeFromThe list ID to unsubscribe from on opt-outNo
OptInSubscribeToThe list ID to subscribe to on opt-inNo
OptInUnsubscribeFromThe list ID to unsubscribe from on opt-inNo
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=example-session-id' \
  -d 'APIKey=example-api-key' \
  -d 'Command=List.Update' \
  -d 'SubscriberListID=123' \
  -d 'Name=Updated List Name'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "List": {
    "ListID": "123",
    "Name": "Updated List Name"
    // Other updated list details...
  }
}
json
{
  "Success": false,
  "ErrorCode": [
    1
  ],
  "ErrorText": [
    "Subscriber list id is missing"
  ]
}
txt
1: Subscriber list id is missing
2: Invalid subscriber list id
3: Invalid opt in mode
4: Invalid opt out scope
5: Invalid send service integration notification setting
6: Invalid setting
8: Data synchronization settings are invalid
9: Invalid email address for reqbyemailsearchtoaddress
10: Invalid opt out suppression list option
11: Nothing to update

Delete Subscriber Lists

POST /api.php

This endpoint allows for the deletion of one or more subscriber lists associated with a user's account. The user must provide the list IDs to be deleted.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandThe API command to execute, which is Lists.Delete for this endpoint.Yes
listsComma-separated list IDs to be deletedYes
bash
curl -X POST https://yourapi.com/api.php \
-H "Content-Type: application/json" \
-d '{"SessionID": "your-session-id", "APIKey": "your-api-key", "Command": "Lists.Delete", "lists": "123,456"}'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}
json
{
  "Success": false,
  "ErrorCode": {
    "lists": 1
  },
  "ErrorText": "Subscriber list ids are missing"
}
txt
1: Subscriber list ids are missing

Retrieve Subscriber Lists

POST /api.php

This endpoint retrieves a list of subscriber lists for the authenticated user, with options to specify the number of records, starting point, order, and additional statistics.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandLists.Get - The command to execute the retrieval of subscriber lists.Yes
RecordsPerRequestThe number of records to return per request.No
RecordsFromThe starting point for records to return.No
OrderFieldThe field by which to order the lists. Default is ListID.No
OrderTypeThe type of order for the lists, either ASC or DESC. Default is ASC.No
bash
curl -X POST https://yourdomain.com/api.php \
-H "Content-Type: application/json" \
-d '{
    "SessionID": "your-session-id",
    "APIKey": "your-api-key",
    "Command": "Lists.Get",
    "RecordsPerRequest": 10,
    "RecordsFrom": 0,
    "OrderField": "ListID",
    "OrderType": "ASC"
}'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "TotalListCount": 25,
  "Lists": [
    {
      "ListID": "1",
      "EncryptedSaltedListID": "e4d909c290d0fb1ca068ffaddf22cbd0",
      "SyncLastDateTime": "2023-01-01 12:00:00"
    },
    {
      "ListID": "2",
      "EncryptedSaltedListID": "ab56b4d92b40713acc5af89985d4b786",
      "SyncLastDateTime": "2023-01-02 12:00:00"
    }
    // ... more lists
  ]
}
json
{
  "Success": false,
  "ErrorCode": 101,
  "ErrorText": "Invalid SessionID or APIKey"
}
txt
101: "Invalid SessionID or APIKey."

Website Event Property List

POST /api.php

This API call will return the list of website event properties for a specific subscriber list ID.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandWebsite_Events.PropertiesYes
ListIDThe subscriber list ID.Yes
bash
curl -X POST http://yourdomain.com/api.php \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "SessionID=your-session-id" \
  -d "Command=website_events.properties" \
  -d "ListID=1"
json
{
  "ListID": "1",
  "Properties": {
    "conversion": [
      "$browser",
      "$browser_language",
      "$browser_version",
      "$current_url",
      "$device",
      "$device_type",
      "$dsn",
      "$host",
      "$lib",
      "$lib_version",
      "$list_id",
      "$os",
      "$pageTitle",
      "$pathname",
      "$referrer",
      "$referring_domain",
      "$screen_height",
      "$screen_width",
      "$sent_at",
      "$server",
      "$uuid",
      "$viewport_height",
      "$viewport_width",
      "conversionId",
      "conversionName",
      "conversionValue"
    ],
    "customEvent": [
      "$browser",
      "$browser_language",
      "$browser_version",
      "$current_url",
      "$device",
      "$device_type",
      "$dsn",
      "$host",
      "$lib",
      "$lib_version",
      "$list_id",
      "$os",
      "$pageTitle",
      "$pathname",
      "$referrer",
      "$referring_domain",
      "$screen_height",
      "$screen_width",
      "$sent_at",
      "$server",
      "$uuid",
      "$viewport_height",
      "$viewport_width",
      "eventName",
      "key1",
      "key2",
      "key3"
    ],
    "identify": [
      "$browser",
      "$browser_language",
      "$browser_version",
      "$current_url",
      "$device",
      "$device_type",
      "$dsn",
      "$host",
      "$lib",
      "$lib_version",
      "$list_id",
      "$os",
      "$pageTitle",
      "$pathname",
      "$referrer",
      "$referring_domain",
      "$screen_height",
      "$screen_width",
      "$sent_at",
      "$server",
      "$uuid",
      "$viewport_height",
      "$viewport_width",
      "emailAddress",
      "name"
    ],
    "pageView": [
      "$browser",
      "$browser_language",
      "$browser_version",
      "$current_url",
      "$device",
      "$device_type",
      "$dsn",
      "$host",
      "$lib",
      "$lib_version",
      "$list_id",
      "$os",
      "$pageTitle",
      "$pathname",
      "$referrer",
      "$referring_domain",
      "$screen_height",
      "$screen_width",
      "$sent_at",
      "$server",
      "$uuid",
      "$viewport_height",
      "$viewport_width",
      "url"
    ]
  }
}
json
{
  "Success": false,
  "ErrorCode": 1,
  "ErrorText": "Missing ListID parameter"
}
txt
1: Missing ListID parameter (HTTP 422)
2: Invalid ListID parameter (HTTP 422)
3: List not found (HTTP 404)

Any questions? Contact us.