Add Subscribers By API Calls

Normally, users register via a subscribe link or the mini-subscribe form, which is easily integrated into your own website. However, if you have already collected all relevant data from a potential subscriber in your system, it is possible to perform the subscription to a list in LISTSERV Maestro directly from your system via an API call. Users will then receive a confirmation email to confirm the subscription, just as they would if they registered directly in Maestro.

A typical usage scenario is this: Let's assume you run an online shop system and one or more lists hosted via Maestro. In this case, you can extend the data you already collect for your system with the data needed to register with a list and transfer it directly to Maestro via API calls. This saves your users from having to go through the Maestro subscribe page and enter their data a second time. Once the data has been successfully transferred to Maestro, the user will receive a double-opt-in confirmation email to verify the supplied email address and to confirm the subscription. After confirmation, the user is subscribed to the list.

Integration

For this function to be available, the public visibility of the list must be set to Open to Everyone (Runtime Status: Full Operation). To change this setting, open the Public Website & Notification Email Settings page of a Standalone List or the List Group to which the list belongs.

You must now configure your external system to make a call to a URL with this format:

https://SERVER_NAME/list/action/addSubscriberExternally.do?mContainer=2&mOwner=N10&mListId=HL%2312&mSubscriber=SUBSCRIBER_DATA

The above URL contains the following parameters, which must be replaced with real values to match your Maestro instance and the desired list:

mContainer: The list group seq-no to which the list belongs
mOwner: The owner scope of the list
mListId: The ID of the list to which the user shall be subscribed
mSubscriber: The data of the new subscriber

Note: The correct action url with the matching parameter values that are required to identify a hosted list can be found in the Subscribes section of the corresponding Public Website Page URLs page of a Standalone List or of the List Group to which the list belongs.

The value for "SUBSCRIBER_DATA" above is supplied in JSON format that has additionally been URL-encoded (in order to be valid as an URL parameter).

A simple example:

{"email":"first.last@example.com"}

In URL-encoded form, looks like this:

%7B%22email%22%3A%22first.last%40example.com%22%7D

A detailed description of the subscriber data format can be found below.

By sending an HTTP GET request to the URL prepared per the instructions above, your system will receive the result of the execution in the HTTP response, also in JSON format. Your system must be programmed to evaluate this result and react accordingly. The exact format of the result is described below.

Subscriber Data

The subscriber data consists of the mandatory property email and a number of other list-dependent or optional properties.

Sample for Subscriber JSON Data:

	{
		"email":"first.last@example.com",
		"password":"jgajgworfsgsggsgg",
		"profile":{"FIRST_NAME":"First","LAST_NAME":"Last"},
		"remoteAddress":"192.168.1.1",
		"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:86.0) Gecko/20100101 Firefox/86.0"
	}

Supported Properties

email: The email address of the user that wants to subscribe to the list [MANDATORY]
profile: The additional profile fields of the list, if any. [MANDATORY, if mandatory profile fields exist, OPTIONAL if not]

Defines the profile associated with the given address. Used to add the subscriber profile. The profile consists of JSON properties for the profile fields of the list. The profile must contain an entry for each mandatory field that does not have a default value. Leaving out entries for such fields will cause the subscription to fail. Depending on the data type of the profile field, these entries can be any of the following:
- "FIELD_NAME":"text"
  A text field with its textual value in double quotes.
- "FIELD_NAME":12345
  A number field with its integer value (without quotes).
- "FIELD_NAME":"selected value"
  Syntactically equivalent to a text field, only that "selected value" is the display text of one of the entries of a lookup table that is assigned to a single-select field.
- "FIELD_NAME":["selected value 1","selected value 2",...]
  Similar to above, only that the associated list field allows multiple selection.
- "FIELD_NAME":true
  A boolean field with its boolean value (without quotes).
In all cases, FIELD_NAME is the name a known profile field of the subscriber list or group.
password: The Maestro login password. If the password attribute is not present, the user is subscribed with a default password created automatically by Maestro. This password can be changed by the subscriber at a later time, if desired. [OPTIONAL]
remoteAddress: The remote ip-address of the original user request. [OPTIONAL]
userAgent: The user-agent string of the user's browser. [OPTIONAL]

Note: Do not forget to finally URL-encode the subscriber data in order to be valid as an URL parameter.

Action Result: Success

	{"result":"SUCCESS"}

This text is returned in the body of the HTTP response if Maestro has successfully performed the subscription of the user with the given email address and profile to the list.

Note: The user must still confirm the subscription via the link in the double opt-in confirmation mail that has been sent during the subscription, exactly as a subscription directly through Maestro would work.

Action Result: Failure

	{"result":"FAILED","reason":FAILURE_REASON}

In the result above, the value for "FAILURE_REASON" itself is supplied in JSON format with the following properties:

type: The value of this property is one of the following error categories:
- PARAMETER_VALIDATION_ERROR: Indicates an error related to the URL parameter values (e.g. missing URL parameter, list not found, owner does not exist, subscriber data not a valid JSON, ...).
- SUBSCRIBE_NOT_POSSIBLE: Indicates that a subscribe to the selected list is not possible because of the current list status (e.g. list definition is incomplete, subscribes are not allowed, ...).
- ALREADY_SUBSCRIBED: Indicates that the specified email address is already subscribed to the list. This is not an error in the strictest sense, since the operation was cancelled. However, you may read this as an actual error in your system because the profile values that were optionally supplied with the call have been ignored completely and the user is still subscribed to the list with unchanged profile values.
- AUTHENTICATION_REQUIRED: Indicates that the specified email address is already a registered member of a list group, but is not yet subscribed to the list. In this case, for security reasons, the subscription via the API call is not possible and the user must use Maestro directly to be able to subscribe (see below).
- PROFILE_VALIDATION_ERROR: Indicates that errors were detected in the specified subscriber profile data during validation (e.g. missing mandatory fields, wrong data type, unknown profile field names, ...).
message: The value of this property is a human-readable error message.
details: This property contains, if available, detailed additional information about the problems encountered in the form of a JSON array (e.g. profile validation errors per field ["error details 1","error details 2",...], ...).
externalSubscribeURL: This URL is only used in case the user has to authenticate to subscribe to the list ("type":"AUTHENTICATION_REQUIRED"). Redirecting to this URL yields the same page in Maestro that is designed for this specific situation (i.e. the user has supplied an address that is already registered in a multi-list group and must now authenticate the subscription by supplying the correct password).