Recipients Selected On Demand By API Calls
Normally, messages sent via LISTSERV Maestro select their recipients actively from some sort of pre-existing repository, either in LISTSERV Maestro's subscriber warehouse or in some imported form. LISTSERV Maestro On-Demand Recipients go beyond this methodology by allowing you to not only trigger a prepared mail job's delivery based on an external event (and then having LISTSERV Maestro perform the necessary steps to gain access to the recipient data) but to also supply the actual recipient data directly with the API call.
A typical usage scenario is this: Assume you run an online shop system that allows customers to purchase merchandise. Typically, upon completion of a purchase, customers expect some form of email confirmation. While shop systems certainly support such completion messages, you may want to employ LISTSERV Maestro's sophisticated tracking and reporting capabilities to measure if and how your customers interacted with the completion message, for example to follow-up on the completion message with additional discount offers or other marketing messages.
Basic Workflow
- Prepare a Mail Job: Since you will be sending email messages via LISTSERV Maestro,
you first need to create a mail job or edit an existing one.
- Edit the recipients of this mail job and choose the recipients type Send to List or Dataset in your Subscriber Warehouse. On the "Source" page of the recipients wizard, select the desired subscriber dataset or list and choose the Advanced Recipient Selection node. On the Source Details page, choose Recipients Selected On Demand By API Calls.
- Define the remaining parts of the mail job workflow and proceed to the authorize delivery screen. Due to the job's special recipients definition, the "Authorize" workflow step activates the capability to accept external API calls for this mail job.
-
Determine the base URL: You will have to configure your shop system to access a special URL in response to the event of a completed purchase. Similar to other actions that are triggerable externally, on-demand recipient API calls go via an external trigger URL, as described here.
Note: Even if processing the provided data supplied with the call fails with an error information as described further below, the associated URL call still succeeds with the HTTP status "200-OK", which means that your system also has to inspect the data provided in the response body if this "OK"-type HTTP response code is returned.
- Acquire the security token for the API URL: Open the summary of your prepared mail job. On this screen you find a link to show the security token.
-
Configure your system to provide recipient data with the triggering URL: With the preparation steps performed so far, you have a base URL for your API calls similar to the following:
http://SERVER_NAME/lui/externalAction.do?token=SECURITY_TOKEN
(The value for SECURITY_TOKEN is the security token acquired from your prepared mail job.)
You now have to configure your external system to supply the value for an additional URL parameter to finally yield a triggering URL in this form:
http://SERVER_NAME/lui/externalAction.do?token=SECURITY_TOKEN&recip=DATA
The value for "DATA" above is supplied in JSON format that has additionally been URL-encoded (in order to be valid as an URL parameter). The full format is described below. A simple example, in URL-encoded form, looks like this:
http://SERVER_NAME/lui/externalAction.do?token=SECURITY_TOKEN&recip=%7B%22email%22%3A%22test%40example.com%22%2C%22ifNotExistsAddAndSend%22%3Atrue%7D
In human-readable form, the value for the "recip" parameter in the example above was:
{"email":"test@example.com","ifNotExistsAddAndSend":true}
If your external system accesses this URL after a customer with the email address "test@example.com" has purchased merchandise from your shop, the following happens in LISTSERV Maestro:
- If the address "test@example.com" does not yet exist in the subscriber list (or dataset) selected in the recipients definition of your prepared mail job, then this address is registered as a list subscriber (or dataset subscriber, depending on your selection in the recipients wizard). Since the URL call did not provide additional recipient profile data, this action only succeeds if your list or dataset does not have boolean or mandatory fields (more below).
- The associated subscriber record is registered as recipient of your prepared mail job and the message of the prepared mail job is sent to the given address.
(Note that the data in the example above included "ifNotExistsAddAndSend" with the value "true". This makes sure that new addresses are also added to the dataset or list.)
- Configure your system to act properly on the HTTP response provided when accessing the URL:
If all data supplied with the URL was processed successfully and LISTSERV Maestro successfully delivered the
associated email message, then the HTTP response consists of the following text:
{"result":"SENT"}
If you receive anything other than the text above, then this means that the message was not delivered. The actual text normally provides details on what happened, so the easiest way to act on the response would be to program your system to handle the delivery as failed and log the response for later troubleshooting.
Even if the example used in the description above is rather simple, it illustrates the basic mechanism and the minimum requirements that an external system must provide in order to properly provide on-demand recipients via URL calls: The ability to access HTTP URLs with dynamic parameters in URL-encoded format and to dynamically act on the associated HTTP response.
Personalizing the message with profile fields
The URL in the basic example above only allows you to send a message with very generic content, i.e not much more than "thank you for your purchase". To employ LISTSERV Maestro's sophisticated mail-merging capabilities, you may want to provide additional information with the email address, for example values for additional recipient profile fields such as the first name or the last name. (These values may in fact be mandatory fields of your list or dataset, which means that the URL call would actually fail if your system did not provide these values with the call.)
To provide profile values in addition to the email address, you augment the (non-encoded) value for the "recip" parameter with the additional "profile" JSON property, e.g.:
With this additional information supplied in the URL call, LISTSERV Maestro also checks if your list or dataset actually contains fields with names "FIRST_NAME" and "LAST_NAME". If they don't exist and have not been configured in the mail job's recipients wizard as "On-Demand Merge Fields" (more on this later), the URL call fails with an appropriate error message. If this validation succeeds, then the values provided with the URL are also used for mail-merging in the message of the associated mail job.
Personalizing the message with additional on-demand merge fields
The profile fields you have configured in your list or dataset are only used for the purpose of sending personalized email messages and do not necessarily contain one-time only information which however may be vital in the context of for example a purchase confirmation or a shipping notice, which typically would include the specific shipping address that was chosen while performing the checkout in your shop system.
If you plan to send messages which contain one-time only information that you do not want to add as profile field to your list, you prepare the mail job in LISTSERV Maestro with additional on-demand merge fields: When preparing your mail job following the procedure described above, you additionally need to open the "Recipients Details" page of the recipients wizard. On this page you see a section Additional On-Demand Merge Fields. Continuing the example of a shipping address that you do not want to appear in the list or dataset profile, you can supply on-demand merge fields here that would constitute a shipping address, for example with several address lines:
With the mail job prepared in LISTSERV Maestro in such a manner, the following value for the "recip" parameter would also be accepted, even if your list or dataset only knows the fields EMAIL, FIRST_NAME and LAST_NAME:
Now that these values are available for mail-merging, you are able to write a generic shipping notice using the variables &FIRST_NAME;, &LAST_NAME;, &SHIPPING_ADDRESS_LINE1;, &SHIPPING_ADDRESS_LINE2; and &SHIPPING_ADDRESS_LINE3;, which appear under "Merge Fields" on LISTSERV Maestro's "Define Message" screen.
Sending Messages to Existing Subscribers
"ifNotExistsAddAndSend":true
Setting this flag allows you to send email also to addresses that previously did not exist on the list or dataset (by first also adding the address with the supplied profile to the list or dataset). If you instead supply the value "false" (or leave out the flag completely), then LISTSERV Maestro instead validates that the given email address already exists, which protects you for example from spelling errors.
By default, when sending messages to existing subscribers, additional profile information you supply with the URL call is ignored, the profile values that exist in LISTSERV Maestro's database take precedence. To override this behavior and to actually also update the data in LISTSERV Maestro with the values you have included with URL, use:
"ifExistsDoUpdate":true
With this, the given profile fields are updated with the values you supply in the URL, the rest of the subscription profile in LISTSERV Maestro remains unchanged.
Overriding Delivery Constraints
LISTSERV Maestro respects certain constraints before sending email messages to subscribers of a subscriber list. A subscriber may for example have chosen to temporarily suspend mail delivery for a given list, or a dataset subscriber may not be subscribed to any of the subscriber lists in the dataset. Or the dataset may be configured so that only up to a certain limited number of mails is sent to a given subscriber in a certain period of time.
Normally, delivery to such subscribers does not happen. Forcing the delivery regardless of such constraints or limitations requires careful consideration because this effectively ignores the subscriber's explicit intention to not receive mail. Examples were such a behavior is not considered problematic are purchase confirmations or shipping notices which legally belong to a business transaction between you and your customer. To enable forced delivery, use:
"ifExistsForceSending":true
Description of the format for the "recip" parameter
- "email":"test@example.com"
Defines the address to which LISTSERV Maestro shall send the email message. Must not be empty and is checked to be a valid Internet email address.
- "profile":{FIELD1,FIELD2,FIELD3,...}
Defines the profile associated with the given address. Used to add/update the subscriber profile or for on-demand mail-merging. Each of "FIELD1", "FIELD2", ... in the pseudo notation above is a JSON property which 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 list or dataset 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 merge field. Merge fields either exist as fields of the underlying subscriber list or dataset or they have been configured in the recipients wizard of the associated mail job as "Additional On-Demand Merge Fields".
- "FIELD_NAME":"text"
Send Result: Success
{"result":"SENT"}
This text is returned in the body of the HTTP response if LISTSERV Maestro has successfully performed the delivery of the email message for a recipient supplied as value for the "recip" parameter.
Send Result: Error
In order for the delivery to succeed, various validation, compatibility and internal checks are performed. If any of these checks fail, then a suitable "result" property other than the above is returned. Possible errors are:
{"result":"PARSE_ERROR", "error":"Parse error in JSON data"}
{"result":"NO_RECIPIENTS", "error":"No recipients specified"}
{"result":"MAIL_JOB_NOT_FOUND", "error":"Mail job not found"}
{"result":"ILLEGAL_JOB_STATE", "error":"Illegal mail job state"}
{"result":"TRIGGER_CLOSED", "error":"Trigger closed"}
{"result":"DATASET_NOT_FOUND", "error":"Dataset not found"}
{"result":"HOSTED_LIST_NOT_FOUND", "error":"Subscriber list not found"}
{"result":"PROFILE_VALIDATION_ERROR", "error":"Profile validation error"}
{"result":"ADDRESS_NOT_FOUND", "error":"No subscriber with specified address found and property ifNotExistsAddAndSend not set"}
{"result":"ADDRESS_REJECTED_BY_SUPPRESSION_LIST", "error":"Address on suppression list"}
{"result":"ADDRESS_REJECTED_BY_LIST_PROTECTION", "error":"List protection is enabled and address was previously unsubscribed or bounced too often"}
{"result":"SEND_ERROR", "error":"Sending failed"}
{"result":"INTERNAL_ERROR", "error":"Internal execution error"}
{"result":"INVALID_EMAIL", "error":"Invalid email address"}
{"result":"MISSING_EMAIL", "error":"Missing email address"}
{"result":"INVALID_DO_UPDATE_FLAG", "error":"Invalid ifExistsDoUpdate property"}
{"result":"INVALID_FORCE_ADD_FLAG", "error":"Invalid ifNotExistsAddAndSend property"}
{"result":"INVALID_FORCE_DELIVERY_FLAG", "error":"Invalid ifExistsForceSending property"}
{"result":"INVALID_PROFILE", "error":"Invalid profile property"}
The properties result and error in the JSON objects listed above are always present in the case of a non-successful send result. Depending on the actual error that occurred, the additional message property provides further details about the error, such as for example input validation error messages in the case of a list or dataset field with custom input validation defined.
Supplying Multiple Addresses
The examples above all trigger the delivery of an email message to one recipient only. If your system needs to trigger delivery for several recipients, then, for convenience, it is possible to supply multiple values for the recip parameter in JSON array format.
This is how you supply one recipient:
{ "email":"test@example.com", "ifNotExistsAddAndSend":true }
To supply multiple recipients, you supply for example:
[{ "email":"test@example.com", "ifNotExistsAddAndSend":true }, { "email":"test2@example.com", "ifNotExistsAddAndSend":true }]
Note the array brackets in the example above. With this syntax, LISTSERV Maestro processes each of the supplied recipients one by one exactly in the same way single recipients are processed. The result provided in the HTTP response body is also a JSON array, whose sequence follows the sequence in which the recipients were supplied. If delivery to all provided recipients succeeds, then the response body looks like this:
[{"result":"SENT"},{"result":"SENT"}]