Q: Is there an API for LISTSERV Maestro?

Answer by Liam Kelly
Senior Consulting Analyst, L-Soft

The purpose of an API (application programming interface) is generally to allow external programs and services to interact with an application. While LISTSERV Maestro doesn't have a unified web services API, there are a number of actions that can be performed via HTTP/HTTPS requests called from external programs. These actions use a security token for authentication and allow an external program to trigger job delivery, export job reporting data, import subscribers from an external data source, or download subscriber data from a Maestro-hosted dataset or list.

Triggered Job Delivery

One way that an external program can interact with LISTSERV Maestro is by triggering delivery of an email job. Triggered delivery requires that all steps in preparing the job (including the Authorize Delivery step) are completed. Under the Delivery Settings step, select the option for "Wait until mail job delivery is triggered". Once the other steps are complete and the job is authorized for delivery, LISTSERV Maestro will create a security token to trigger the job delivery. The security token can be viewed by looking at the Job Summary under the "Ongoing Jobs" tab. Scroll to the bottom of the job summary, and click "Show Security Token for Delivery Trigger" to display the token. The delivery is triggered by calling a URL that looks something like the following:

• SERVER_NAME is replaced with the name of your LISTSERV Maestro server, for example, LISTSERV.EXAMPLE.COM. (If a non-standard HTTP port is used, also include the port, separated with a colon ":". If access to your LISTSERV Maestro is protected with HTTPS, you need to specify "https://" instead of "http://".)
• SECURITY_TOKEN is replaced with the security token as described above.

Triggered delivery is especially useful for cases when you may need to have delivery triggered automatically after drop-in content or subscriber data is updated in a DBMS. If the job is created as an auto-repeat job, the trigger can be called multiple times. As an example, we might create an auto-repeat job that pulls breaking news headlines from a DBMS to be used as drop-in content in the message. We might not run that job on a scheduled basis, but instead trigger it whenever some external process populates the DBMS with new headlines. In this case, we could have an external program call the Maestro delivery trigger URL (with security token) once the DBMS update was completed.

More information about triggered job delivery is available on the "Delivery Settings" help page in LISTSERV Maestro.

Exporting Job Data

Another action that can be performed externally with a security token is downloading of job data. This can be useful if you have some external system into which you want to automatically load Maestro delivery and tracking statistics. Like triggered job delivery, the export is launched by calling a special URL with a security token:

There are a number of parameters that can be passed in the export URL to tell LISTSERV Maestro to export events for a particular job, a particular date range, or a particular auto-repeat job chain. The output is an XML file that provides the requested statistics in a format suitable for import into any system that can parse XML. Listing all of the parameters is beyond the scope of this Tech Tip. For details about enabling job data export, passing parameters and parsing the XML output, see the following whitepaper:

Exporting LISTSERV Maestro Job Data to an XML File:
http://www.lsoft.com/resources/whitepaper-download.asp?id=305

Importing Subscribers

Another API-like feature of LISTSERV Maestro is the ability to remotely trigger a subscriber import from some external system into a Maestro-hosted dataset or recipient list. A common use of this would be to prompt LISTSERV Maestro to query a DBMS to update or replace list membership data.

Member importers can be used to update membership of either a Maestro dataset or a subscriber list within a dataset. From the "Dataset" or "Hosted List" menu, select "Member Import" or "Subscriber Import". From here, you can create, view, edit or launch an importer. Imported subscribers may come from one of two places: either a DBMS or a file stored on the server. Creating an importer will walk you through the steps necessary to define the source as well as other settings like default values and synchronization options. Once the importer is defined, the summary screen will display a security token that can be used to launch the importer remotely. The URL format is similar to that used to trigger job delivery:

For more documentation on triggered subscriber imports, see the online help. From the "Member Importers / Subscriber Importers" page -> Select a dataset, then in the menu "Dataset" -> "Member Import" -> "View Member Importers"; or select a hosted list, then in the menu "Hosted List" -> "Subscriber Import" -> "View Subscriber Importers", see the help page.

Downloading Subscribers

Just as a triggered import can be used to import subscribers into LISTSERV Maestro from an external system, so a triggered export can be used to download subscribers from Maestro. To view the download security token for a dataset, select a dataset, then select the menu item "Dataset" -> "Edit Dataset Settings". Click "Show Advanced Settings", then "Show Download Security Token". To view the download security token for a hosted list, select the hosted list, then select the menu item "Hosted List" -> "Edit List Details". Click "Show Download Security Token". Once you have the download token, the launch URL is similar to the other triggered actions URLs:

The output will be a comma-separated file containing the data from the dataset or hosted list. For more information, see the online help. Select a dataset, then in the menu "Dataset" -> "Dataset Overview" or select a hosted list, then in the menu "Hosted List" -> "Edit List Details", see the help page of the "General" page in the wizard.

Subscribe to LISTSERV at Work.