NAV

Distribution List API(Last Updated : 01/11/2017)

A distribution list enables you to create a specific group of subscribers. The list can then be used for targeted messaging or marketing campaigns, which means you are reaching only the most relevant subscribers.

Creating a Distribution List

A Distribution List requires the following four contents. For more details on each of them, please refer to the REST API documentation.

Fields

Field Name Description
List name The unique name of the distribution list. This name is referenced for any API calls using lists.
Display name of List The display name is the name your subscribers will see when signing up for your list. This name is public, so it should be something your subscribers can understand.
Frequency Industry regulations require you to disclose the message frequency for your campaigns.
Description You must provide a description of the messages your subscribers will be receiving when they opt in.

The following example shows how to create a Distribution List.

ApiClient apiClient = ... ApiContext apiContext = ... DistributionList distributionList = new DistributionList.Builder() .uniqueName("myList") .displayName("My List") .description("My first list created using Trumpia REST API SDK") .frequency(1) .build(); try { DistributionListCreationResult result = DistributionApi.with(apiContext) .create(distributionList) .executeOn(apiClient); // Process the result... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

After making a request, a DistributionListCreationResult will be returned. It will contain the following information:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getListId(): long List ID to be created The key for the created distribution list.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.

Final results will be pushed to the URL that you specified via Push Notifications. For more details, please refer to this page.

Retrieve All Distribution Lists

You can retrieve the basic information for all of your distribution lists. The following is an example:

ApiClient apiClient = ... ApiContext apiContext = ... try { List<DistributionListSummary> list = DistributionListApi.with(apiContext) .listAll() .executeOn(apiClient); // Process list info... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

Each DistributionListSummary object contains the following methods.

Fields

Method Name Data Returned Description
getId(): long List ID The key for the created distribution list.
getName(): String List Name The name of the distribution list. This name is referenced for any API calls using lists.

Certain Distribution List Retrieval

Once you have retrieved the Distribution List ID, you can obtain details about the list. The following is an example:

ApiClient apiClient = ... ApiContext apiContext = ... try { long listId = 12345L; DistributionListInfo listInfo = DistributionListApi.with(apiContext) .get(listId) .executeOn(apiClient); // Process list info... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

The result DistributionListInfo has the following contents.

Fields

Method Name Data Returned Description
getName(): String List name The name of the distribution list. This name is referenced for any API calls using lists.
getDisplayName(): String Display name of List The display name is the name your subscribers will see when signing up for your list. This name is public, so it should be something your subscribers can understand.
getFrequency(): int Frequency Industry regulations require you to disclose the message frequency for your campaigns.
getDescription(): String Description You must provide a description of the messages your subscribers will be receiving when they opt in.
getSubscriptionCount(): int Subscription count Total number of subscribers in the list.
getMobileCount(): int Mobile count Total number of mobile numbers in the list.
getEmailCount(): int Email count Total number of emails in the list.

Distribution List Update

You can also update an existing Distribution List. To update a Distribution List, you must pass one of the following parameters:

Fields

Field Name Description
List name The unique name of the distribution list. This name is referenced for any API calls using lists.
Display name of List The display name is the name your subscribers will see when signing up for your list. This name is public, so it should be something your subscribers can understand.
Frequency Industry regulations require you to disclose the message frequency for your campaigns.
Description You must provide a description of the messages your subscribers will be receiving when they opt in.

Here is an example that shows you how to update a Distribution List:

ApiClient apiClient = ... ApiContext apiContext = ... DistributionListUpdate listUpdate = new DistributionListUpdate.Builder() .displayName("Fantastic 4") .uniqueName("blahblah") .frequency(4) .build(); try { long listId = 12345L; DistributionListUpdateResult result = DistributionListApi.with(apiContext) .update(listId, listUpdate) .executeOn(apiClient); // Process with result... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

The BasicApiResult object is returned when you update a Distribution List. It contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.

Final results will be pushed to the URL that you specified via Push Notifications. For more details, please refer to this page.

Distribution List Delete

You can delete a Distribution List you have created. The following is an example of how to delete it:

ApiClient apiClient = ... ApiContext apiContext = ... try { long listId = 12345L; DistributionListDeletionResult result = DistributionListApi.with(apiContext) .delete(listId) .executeOn(apiClient); // Process with result... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

The BasicApiResult object is returned when you delete a Distribution List. It contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.

Final results will be pushed to the URL that you specified via Push Notifications. For more details, please refer to this page.

Report Retrieval

You can retrieve the status of your distribution list creation/update/deletion request. The following example shows how you can use the Result object from your API request to make a call which will fetch the status of that request.

ApiClient apiClient = ... ApiContext apiContext = ... try { long listId = 12345L; DistributionListDeletionResult delResult = DistributionListApi.with(apiContext) .delete(listId) .executeOn(apiClient); VariableResult<DistributionListReport, ApiStatusReport> report = delResult.getReportRequest(apiContext) .executeOn(apiClient); // Process the report... } catch (IOException e) { // Handle general IO exceptions } catch (ApiException e) { // Handle API exceptions logger.error("API error: statusCode={}, rawContent={}", e.getStatusCode(), e.getRawContent()); }

VariableResult

After retrieving the report, you will receive an VariableResult object that is either a success or a failure status. For more details please refer to the javadoc.

Distribution List Create/Update/Delete Report

The report returned for the Creation/Update/Deletion of a Distribution List are all the same.

If the list was created/updated/deleted successfully, a report request will return a VariableResult object with a DistributionListReport object which contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getPushId(): long Push ID The key for the specific push message.
getId(): long List ID The key for the created/updated/deleted distribution list.

If the list was not created/updated/deleted successfully, a report request will return a VariableResult object with an ApiStatusReport object which contains the following fields:

Fields

Method Name Data Returned Description
getRequestId(): String Request ID The key for the specific request.
getPushId(): long Push ID The key for the specific push message.
getStatusCode(): String API Status Code A code that provides additional information about the status of your request. Please reference the Status_code list for details.