Editing Distribution Lists and Address Books in NowSMS

Topic Keywords: address book, bulk SMS, distribution lists

One feature of NowSMS that is not very well documented is distribution lists.  Distribution lists are part of the NowSMS web interface, but they are also available for use by other applications.  It is possible to send a bulk SMS message to all of the phone numbers in a distribution list via direct URL submission without using the built-in NowSMS web forms.

To keep your distribution lists up-to-date, it is also possible to have an external application manage them, rather than making manual edits via the NowSMS web interface. This is actually quite easy to do because the distribution lists are just text files stored on the NowSMS server, and can be edited external of NowSMS.

Alternatively, NowSMS provides an HTTP interface that can be used to create/modify/delete distribution lists, and to update the distribution list members. This interface can be used by applications to keep distribution lists up-to-date.

This article will provide more detail on these capabilities.

When submitting messages via HTTP, the recipient address is specified in the “PhoneNumber=” URL parameter. For example:

http://127.0.0.1:8800/?PhoneNumber=xxxxxxxx&Text=abc+def+ghi

You can include multiple recipients in a URL request by separating them in the “PhoneNumber” parameter with a “,” (comma). For example:

http://127.0.0.1:8800/?PhoneNumber=xxxxxxxx,yyyyyyyy&Text=abc+def+ghi

Or some environments may require the comma character to be URL escaped as %2C. For example:

http://127.0.0.1:8800/?PhoneNumber=xxxxxxxx%2Cyyyyyyyy&Text=abc+def+ghi

There is no limit on the number of recipients that can be specified in a URL request (NowSMS dynamically allocates more memory as required). However, the software that you are using to submit the HTTP request to NowSMS might impose a limit on the HTTP URL length.

The above examples all show HTTP GET transactions. HTTP POST can also be used, with the same variable names and formats, using the standard “form value” MIME type of application/x-www-form-urlencoded.

It is also possible to create distribution lists that are kept on the NowSMS server. These are simple text files that contain a list of phone numbers. You can send a message to a distribution list by specifying the distribution list name in the “PhoneNumber” parameter. (Or you can specify multiple distribution lists or a mix of phone numbers and distribution lists separating each entry with a “,”.) For example:

http://127.0.0.1:8800/?PhoneNumber=DlistName&Text=abc+def+ghi

If the distribution list is a public distribution list, it must be prefaced with the # character when sending to the list. For example:

http://127.0.0.1:8800/?PhoneNumber=#DlistName&Text=abc+def+ghi

The web interface also includes functionality to upload distribution lists to the server as simple text files. But it is also possible to edit and manage them externally from NowSMS if desired.

These distribution list files are stored under the DLISTS\username directory on the NowSMS server. (Or directly under the DLISTS directory for public distribution lists accessible to all user accounts.)

Each distribution list has a “.txt” file extension, and the format of the file is one phone number per line of text. Optionally, the phone number can be followed by a descriptive name (e.g., “phonenumber – Full Name”)

There is also an HTTP based API that allows you maintain distribution lists from an external application.

This interface is accessed via the NowSMS web interface port, with a URI of “/DLists” followed by a series of “HTTP GET” parameters.

All requests require user authentication by an account defined in NowSMS under “SMS Users”. Public distribution lists can only be managed by a user account that has “Admin Access” enabled. User account and password in the “User=” and “Password=” parameters of the request, or include an “Authorization:” header using HTTP Basic Authentication.

The following parameters are supported:

DListAction=List, Delete or Add
DListName=Name of Distribution list
DListPublic=Yes or No (default is No)
DListMemberAction=Add or Delete
DListMember=Phone number
DListMemberName=Full Name (always optional)

To create a distribution list, use:

DListAction=Add
DListName=Name of Distribution list
DListPublic=Yes (optional, default is No)

To delete a distribution list, use:

DListAction=Delete
DListName=Name of Distribution list
DListPublic=Yes (optional, default is No)

To return a list of all defined distribution lists, use:

DListAction=List
DListPublic=Yes (optional, default is No)

To return a list of all entries defined to a distribution list, use:

DListAction=List
DListName=Name of Distribution list
DListPublic=Yes (optional, default is No)

To add an entry to a distribution list, use:

DListName=Name of Distribution list
DListPublic=Yes (optional, default is No)
DListMemberAction=Add
DListMember=Phone number
DListMemberName=Full Name (optional)

To remove an entry from a distribution list, use:

DListName=Name of Distribution list
DListPublic=Yes (optional, default is No)
DListMemberAction=Delete
DListMember=Phone number
DListMemberName=Full Name (optional)

As an example, to add a member to an existing distribution list, issue the following URL request:

http://server:port/dlists?User=username&Password=password&DListName=dlistName&DListMemberAction=Add&DListMember= 1234&DListMemberName=Me

The “DListAction=List” response will return an HTTP response of the “text/plain” content type with a list of items. However, all other actions will return an HTML (text/html) response that is expected in the user interface. A program that is issuing HTTP requests programmatically should ignore the HTML content in the response and should look at the HTTP response code (e.g., 200 OK) to determine whether or not the request succeeded.