Distribution lists

Creating distribution lists

Distribution lists can be created within the default workspace or within a specific workspace. Distribution lists can contain contacts and nested distribution lists to create any structure that is required within your environment.

The MRI value is important here. It’s the required unique identifier for any communications that are to be sent to this distribution list.

To create a new distribution list you can use the /distributionlists endpoint.

Only 4 fields are required:

  • name: The name of the distribution list to be created.
  • access: Open or Restricted.
  • visibility: Private or Public.
  • type: Static or Dynamic.

In the case of dynamic distribution lists, there are more required fields:

  • name: The name of the distribution list to be created.
  • access: Open or Restricted.
  • visibility: Private or Public.
  • type: Dynamic.
  • entityType: contact (limited to contacts at the moment).
  • rules: The objects that specify the rules that should be applied on the entityType values to pick the appropriate contact at the moment of usage (not creation). The rules contain an array of rule definitions with a minimum of one rule to be defined. If not done so, a 422 unprocessable entity is returned by the API during the distribution list creation/edit.

Note: The contactIds, userIds and distListIds values are ignored when the type is dynamic, as it’s the rules that govern the members of the distribution list.

High-level request elements

name

String

Specifies the name of the distribution list. This has to be unique, and should not contain any special characters (except spaces) in it.

description

String

Specifies a description for other users to see what this distribution list should be used for.

access

String

Allows you to specify the access type for this DL.

  • Open: Anyone can subscribe to this distribution list via the Whispir Contact Portal.
  • ByApproval: Anyone can subscribe using the Whispir Contact Portal. However, they are not officially on the list until their access is approved.
  • Restricted: The distribution list is not visible in the Whispir Contact Portal.

visibility

String

Allows you to specify the visibility for this DL.

  • Public: Any user or active contact in any workspace can map themselves to this DL in the Whispir Contact Portal.
  • Private: Only users or active contacts in the current workspace can map themselves to this DL.

type

String

Allows you to specify the type for this DL. The default is ‘static’.

  • Static: The contacts on the list don’t change unless you manually add or remove them (unlike a dynamic DL).
  • Dynamic: The contacts on the list change based on the rulesFilter applied at the time of usage. Contacts may change for each run depending on the rules applied to the DL.

entityTpe

String

Only mandatory when the type is ‘dynamic’. The value is currently strictly limited to ‘contact’.

rules

Object

The rules contains array (child) of rule definitions. Each rule is an object with 3 keys in it.

  • ruleFilter: contains any of the contact profile elements that are available for searching. For example, division, department, role.
  • ruleFilterActualName: Contains the matching string to be compared for the DL.
  • ruleContent: Contains the matching string to be compared with the contact element for being a part of the DL.

contactIds

String

Comma separated list of userIds who can have access to/visibility of this DL. This information can be provided at the time of the DL creation or later updated via a PUT request.

userIds

String

Comma separated list of userIds who can have access to/visibility of this DL. This information can be provided at the time of the DL creation or also later updated via a PUT request.

distListIds

String

Comma separated list of Distribution List IDs that can be nested under this DL.


List of common ruleFilter and ruleFilterActualName values

Common Values

If your company has custom contact properties that you want to include in the DL ruleFilter, contact your Whispir account manager or the Whispir Support Team for more information.

ruleFilter: ruleFilterActualName

  1. businessUnit: Business Unit
  2. companyName: Organisation Name
  3. createdtime__timestamp: Created Time
  4. department: Department
  5. division: Division
  6. firstName: First Name
  7. group_messagingoption_active__boolean: Is Active
  8. group_messagingoption_fieldmapping: Mapped Field
  9. group_messagingoption_type__dropdown: Type
  10. jobTitle: Job Title
  11. lastName: Last Name
  12. lastmodifiedtime__timestamp: Last Updated Time
  13. personalAddress1: Personal Address1
  14. personalAddress2: Personal Address2
  15. personalCountry: Personal Country
  16. personalEmailAddress1: Personal Email Address
  17. personalEmailAddress2: Personal Email Address Secondary
  18. personalMobilePhone1: Personal Mobile Phone Primary
  19. personalMobilePhone2: Personal Mobile Phone Secondary
  20. personalPhone1: Personal Phone Primary
  21. personalPhone2: Personal Phone Secondary
  22. personalPhoneAreaCode1: Personal Phone Areacode Primary
  23. personalPhoneAreaCode2: Personal Phone Areacode Secondary
  24. personalPostCode: Personal Postcode
  25. personalState: Personal State
  26. personalSuburb: Personal Suburb
  27. role1: Role
  28. role2: Additional Role
  29. teamName1: Team Name
  30. teamName2: Additional Team Name
  31. timezone: Time zone
  32. workAddress1: Work Address1
  33. workAddress2: Work Address2
  34. workCountry: Work Country
  35. workEmailAddress1: Work Email Address Primary
  36. workEmailAddress2: Work Email Address Secondary
  37. workMobilePhone1: Work Mobile Phone Primary
  38. workMobilePhone2: Work Mobile Phone Secondary
  39. workOtherPhone: Phone Other
  40. workPhone1: Work Phone Primary
  41. workPhone2: Work Phone Secondary
  42. workPhoneAreaCode1: Work Phone Areacode Primary
  43. workPhoneAreaCode2: Work Phone Areacode Secondary
  44. workPostCode: Work Postcode
  45. workPostalAddress1: Work Postal Address1
  46. workPostalAddress2: Work Postal Address2
  47. workPostalCountry: Work Postal Country
  48. workPostalPostCode: Work Postal PostCode
  49. workPostalState: Work Postal State
  50. workPostalSuburb: Work Postal Suburb
  51. workSetellitePhone: Satellite Phone
  52. workState: Work State
  53. workSuburb: Work Suburb

  • JSON
  • XML

Creating distribution lists

Distribution lists can contain lists of contacts and other distribution lists.

{{codeStart}}

POST https://api.<region>.whispir.com/distributionlists?apikey=[your_api_key]

Authorization: Basic asdf98nf89asdvasd2r398h8sdf

x-api-key: your_api_key

Content-Type: application/vnd.whispir.distributionlist-v1+json

{

"name" : "My Distribution List",

"description" : "",

"access" : "Open",

"visibility" : "Public",

"contactIds" : "",

"userIds" : "",

"distListIds" : ""

}

{{codeEnd}}

Users should expect a 201 Created response after executing this request.

 

Creating dynamic distribution lists

Dynamic distribution lists contain rules with filters to determine the members dynamically:

{{codeStart}}

POST https://api.<region>.whispir.com/distributionlists?apikey=[your_api_key]

Authorization: Basic asdf98nf89asdvasd2r398h8sdf

x-api-key: your_api_key

Content-Type: application/vnd.whispir.distributionlist-v1+json

{

"name" : "My Dynamic DistributionList",

"description" : "My Distribution list",

"access" : "Open",

"visibility" : "Public",

"type" : "dynamic",

"entityType" : "Contact",

"rules" : [{

"ruleFilter" : "division",

"ruleFilterActualName" : "Division",

"ruleContent" : "sales"

},{

"ruleFilter" : "businessUnit",

"ruleFilterActualName" : "Business Unit",

"ruleContent" : "apac"

}]

}

{{codeEnd}}

Users should expect a 201 Created response after executing this request. If the rules are incorrectly passed, then a 422 Unprocessible Entity response is thrown.