Subscriber List Definition

The Subscriber List wizard lets you define the settings of a subscriber list or edit an existing list.

Note: A subscriber list is only fully editable while it is "empty", meaning that there are no subscribers on the list. For a non-empty list, only certain settings are editable.

For a Hybrid Subscriber List (which augments the features of a standard subscriber list with the advanced features of a LISTSERV list, covering advanced use cases such as email discussions groups), the wizard has eight pages:

General, List Type, List Options, Posting Restrictions, Topics, Profile Fields, Profile Field Details, and Summary

The top row of the wizard displays links to these pages. The page that is currently open is highlighted. Depending on the choices made on some of the wizard pages, other pages may become disabled or may be shown in different versions. If a wizard page is disabled, then it means that this page is not necessary with the current choices and can safely be ignored.

General Page: List Name, Subscription Consent and Advanced List Settings

This screen defines the general settings of the subscriber list:

• List Name: The name of the subscriber list is used internally in LISTSERV Maestro and is displayed externally to subscribers as the name of the list.

  If the list is a Hybrid Subscriber List, then the name must also be unique on the LISTSERV instance that your account is connected to (there cannot be two LISTSERV lists with the same name on the connected LISTSERV server).
  Depending on the configuration in the Administration Hub, it may be that all Hybrid Subscriber Lists that belong to your account or group will have an automatic name suffix that is always appended to the name that you enter here (a hyphen is used as a separator). If this is the case, then this suffix is displayed immediately to the right of the Name field.

• Explicit Subscription Consent: Define if the list shall have a special subscription consent profile field or not.

  A field of this type behaves just like a field of type "True/False", but with the additional semantic that the subscriber must check the corresponding checkbox, or otherwise he is not allowed to subscribe to the list. As such, the field can be used to record the subscriber's consent to the subscription terms for the given list. If no consent is given, a subscription is simply not allowed.

  If you select to include this consent field, then you must also fill out the edit field with the subscription terms that the subscriber is asked to consent to. These terms will be displayed together with the input field.

  Note: Any changes to this profile field are logged. That way, you can later reconstruct exactly when a subscriber consented to the subscription terms.

Advanced Settings

• External Download: The subscribers of the list can be downloaded via an external download URL, i.e. an URL that can be accessed without first logging in to Maestro. This external download URL is a so-called "external trigger" of the type "Simple URL Access", with the download data in the body of the HTTP response (in form of a ZIP file). See below for more details about external triggers and what this means in detail.

  For the external trigger, a special security token is required. Each list has a unique download security token.

  Important: Everyone who is in possession of this security token and who can also access Maestro on its HTTP port (for example with a normal web browser) is able to download the list subscribers. The security token should therefore be closely guarded and not be given out to unauthorized persons. Because of this, the screen does not display the token directly (so no one can simply look over your shoulder and "steal" the token). To display the token, you first have to click on the Show Download Security Token link.

  Creating a new Download Security Token: If you suspect that an unauthorized person has gained access to the download security token, you can use the Create New Download Security Token link to invalidate the previously used token and to create a new one.

• Individual Email Limit: (Only available for standalone lists. In list groups, the group defines the limits for the whole group and all lists in it.)

  Define if there shall be a limit for each subscriber of how many individual emails shall be sent to that subscriber. If this option is enabled, then you also need to fill out the values for the "No more than [ X ] emails over [ Y ] days" edit fields.

  The limit works as follows: If a mail job is sent to this list, then subscribers that already received X emails during the last Y days will not receive this message, even if they otherwise fulfill all conditions for a recipient of the mail job.

• Data Encoding: (Only available for standalone lists. In list groups, the group defines the data encoding for the whole group and all lists in it.)

  The encoding used to store the profile values of the subscribers. Select an encoding that matches the language that is going to be used when the profile fields are being filled out.

  Note: The encoding can no longer be changed once there is at least one subscriber on the list. It can only be changed while the list is still empty.

• Expected Growth: The values specified here define the thresholds that Maestro uses to declare a list's growth as healthy or not. This is for example used to determine if a subscriber warehouse health alert is given, or to highlight a list growth that is below expectations.

  The expected growth is specified for 7, 30 and 90 day intervals, allowing you a fine grained control of this metric.

  For a list where you expect continuous growth (with more and more subscribers), you can specify a percentage value of your expected minimum growth. For example, if you specify "3%", then you expect the subscriber count to grow by 3% or more during the given interval. LISTSERV Maestro will then alert for any growth that is below 3%, and of course it would also alert if the list size would shrink, instead of grow.

  For a list where you actually would accept (or maybe even expect) a shrinkage, you can still specify a threshold. In this case you specify it as a negative value, defining the maximum expected shrinkage. For example, if you specify "-5%", then you expect the list to shrink a bit, but no more than by 5%. Maestro will then alert for any shrinkage of more than 5%.

  You can also define even adds or deletes by the list owner shall be factored in when determining the list growth or not. If not, then only subscribes and unsubscribes by the subscribers themselves will be counted.

External Triggers

LISTSERV Maestro offers several actions that can be triggered remotely from an external source by simply accessing a special external trigger URL, via the HTTP protocol. This trigger URL can be accessed without the need to first login to Maestro.

With this, several scenarios are possible:

• If there are actions that need to be triggered manually by a user who does not want to login to Maestro first; then, the user could create bookmarks in his browser, where each bookmark contains a trigger URL and stands for an action that can be triggered. Or, perhaps a custom-made HTML page could be created with links that point to the trigger URLs.

• In a different scenario, these actions could be triggered by another process, such as a script or program. To trigger an action, all this other process has to do is to open a HTTP communication to the action's trigger URL. This type of external process could, for example, trigger an action according to a certain time schedule or each time a certain outside event happens.

To secure the external trigger URLs against unauthorized access, a security token needs to be included in each URL. Each action that can be triggered externally has a unique security token. Therefore, the security token in the URL serves two purposes: It identifies the action that is to be triggered, and it validates that the user or process that makes this request is indeed authorized to do so.

The security token for the action in question can be obtained from inside of the Maestro user interface. The exact location where the token can be obtained depends on the action that it stands for. Please see the description of the action in question for this information.

Important: You should make sure that this security token is not given out to unauthorized persons because anyone who knows the security token of a certain action is able to trigger this action, as long as he also has HTTP access to the Maestro server. If you suspect that an unauthorized person has gained access to the token, then you can create a new token (and invalidate the existing token) by clicking the appropriate link at the location where you obtained the token.

A trigger URL always has the following form:

http://SERVER_NAME/lui/externalAction.do?token=SECURITY_TOKEN

• where SERVER_NAME is replaced with the name of your Maestro server. (If a non-standard HTTP port is used, also include the port, separated with a colon ":". If access to your Maestro is protected with HTTPS, you need to specify "https://" instead of "http://".)

• where SECURITY_TOKEN is replaced with the security token for the action that the URL shall trigger.

External triggers come in two variants:

• Simple URL Access: The action is triggered by accessing the external trigger URL with a HTTP GET request.

  By accessing this URL, a HTTP GET request is made to Maestro. The server then first verifies the given security token and, if it is valid, triggers the corresponding action. The result of the action is returned in the form of a HTTP response.

  If everything went well, a response with the status code "200 - OK" is returned. In this case, the response body contains the result of the action. Most actions return a simple "OK" text in the result, but some actions may also return more data in the result; for example, if the purpose of the action was to download certain data from Maestro.

  If there was a problem executing the action, a response with a different status code is returned, such as "404 - Not Found" if an invalid security token was specified.

• URL Access with Additional Data: The action is triggered by accessing the external trigger URL with a HTTP POST request.

  In contrast to the "simple URL access" of above, the trigger URL must be accessed with a HTTP POST request, and the additional data that is necessary for the action must be included as part of the request body. The data that is required depends on the action in question. Please see the description of the action for this information.

  The result of the action is returned in form of a HTTP response, just like for the "simple URL access". Please see above for details.