Delivery Settings

Information about when and how often to deliver the email job.

Basic Delivery Options

To schedule a job for delivery, select the option for the delivery scheduling desired. There are three basic options for scheduling the delivery of the job after it has been authorized:

• Immediately begin delivering the mail job: With this option, the job will be delivered immediately after it is authorized.

• Wait until mail job delivery is triggered: With this option, the authorized job will not be delivered until delivery is triggered explicitly. This means that the authorized job remains in a waiting state (in the Ongoing Jobs list) until this trigger happens. The delivery can be triggered manually from inside of LISTSERV Maestro or through an external trigger of the type "Simple URL Access" (see below). The security token that is required for the external trigger can be obtained from the job's details page once the job has been authorized for delivery.

• Schedule the mail job delivery to begin at the following time: With this option, the user can specify the exact date and time to begin delivery of a job. Enter both the date and time in the format shown at the right of the edit boxes. Scheduled delivery dates and times must occur in the future of your present session for this to work correctly.

The authorization for delivery occurs in its own job-related workflow step that can only be executed after the delivery schedule is defined.

If any user defined drop-ins are included in the message content, then there is also the following option available:

• Refresh user drop-ins at time of delivery: If selected, then the values for all user defined drop-ins are freshly determined just before delivery, which means that the final delivery is sure to include the latest state of these drop-ins, but can potentially have different values than were seen during test delivery. If not selected, the final delivery will be done with the same values for the user defined drop-ins as the last test delivery, which means that it will not necessarily reflect the most current state of these drop-ins.

Advanced Delivery Options

In addition to the basic options described above, there may also be advanced options available for defining the delivery schedule.

The advanced options are disabled by default. Click on the Click to enable link to enable the advanced options. If you want to disable the advanced options at a later time, click on the Click to disable link that appears together with the advanced options. The advanced options are enabled or disabled on a per-job basis.

The advanced options available are:

• Normal Delivery: With this option, the mail job is delivered only once, at the delivery time specified in the basic options (see above), and it will be delivered to exactly the recipients that exist at delivery time, no more, no less. This is the default. It is also used when the advanced delivery options are disabled.

  If any user defined drop-ins are included in the message content, then there is also the Refresh user drop-ins at time of delivery available. See above for a more detailed explanation of this option.

• Auto-Repeat Delivery: With this option, the mail job is initially delivered to the recipients that exist at delivery time. However, Maestro will continue to scan for further additional recipients that may become available over the specified auto-repeat delivery period.

  • Delivery Schedule: The auto-repeat delivery period can be set to either open-ended or to end at a specific date and time. Additionally, configure the delay interval between repeated deliveries. With an hourly delay interval, each delivery happens at the same minute as the original delivery, delayed by the configured amount of hours. A daily delay interval works by using the same hour and minute of the original delivery and delaying by the configured amount of days. Weekly and monthly delay intervals work similarly, using the same day of week (or day of month, respectively) as the original delivery and delaying by the configured amount of weeks (or months).

    During this period, at the configured delay intervals, Maestro will scan again for recipients. If any recipients are found, then the same content is sent to these recipients as was sent to the initial recipients.

    Triggered auto-repeat delivery: If you chose triggered delivery in the basic options above, then each delivery occurs when triggered. Right after the triggered delivery has occurred, Maestro will once again wait for the delivery trigger, and so on, until stopped manually.

    Standard auto-repeat delivery: The job will be delivered for the first time at the time specified in the basic options (see above). Right after the job has been delivered, a subsequent delivery (of the same job or of a content variant, see below) is scheduled at a given interval after the first delivery.

    Once this delivery has been processed, another delivery is scheduled for a time that is offset from the previous delivery by the same interval, and so on, until the defined auto-repeat end condition is met (see below).

    If non-triggered delivery is chosen, then you must supply the delay interval between each repeated delivery by entering a positive value into the Delay interval between repeated deliveries field and choosing an appropriate time unit from the selection list.

    In addition, you must specify the end condition to stop the auto-repeat delivery. Select one of these options:

    • Repeat until stopped manually: After each delivery, a new auto-repeat delivery will always be scheduled. This can only be stopped manually.

    • Repeat until date/time: With this option you must specify the threshold date and time to stop the auto-repeat delivery. After each delivery, a new delivery is scheduled only if its designated delivery time (the time of the previous delivery plus the specified interval) is not later than the date and time specified here.

  • Handling of Changes to Drop-In Values: If you choose the Honor changed drop-in values and create content variants option, Maestro creates so-called Content Variants. Further information concerning auto-repeat delivery and content variants is shown below.

  • Duplicate Handling: Each single repeated delivery once again retrieves the job's recipients according to the recipient definition and performs the defined duplicate elimination (if any) within this set. Even after duplicate elimination, it can however happen that the same recipient is once again encountered, that was already included during an earlier delivery. Usually, sending a duplicate message to such a recipient is not desired, but, depending on the nature of your message, you may want to decide to send such duplicates.

    If you disallow duplicate messages, you can for example configure a job based on a Subscriber List and set it to use auto-repeat delivery. For such a job, the initial delivery includes all subscribers of the list as recipients. With auto-repeat delivery active, after each configured delay interval, the job is again sent to all subscribers of the list that did not already receive the message. In other words, the previously existing subscribers will be ignored during this repeated deliveries, as they already received the message. But any new subscribers that are added to the list during the repeated delivery period will then also receive the message.

    An alternative to this would be a job that was defined with a condition to only include subscribers that specified "Sweden" as the country of residence. The initial delivery therefore included only the subscribers with this profile setting. With auto-repeat delivery active, on each of the following repeated deliveries, the job will again be sent to all subscribers with "Country=Sweden" that did not already receive the job. This can potentially include two types of subscribers: New subscribers that were not on the list during the initial delivery and that subscribed at a later time, with "Country=Sweden" in their profile. But also existing subscribers that were already on the list during the initial delivery, but who at this time had specified a country different than Sweden (and which were therefore not included as recipients), who have since then moved to Sweden and have therefore modified their country profile field, so that now they do fulfill the recipient selection condition.

    When preventing duplicates, you have two options:

    • Prevent duplicate messages for job: This option prevents all duplicates of later repeated messages to the same recipient.

    • Prevent duplicate messages for same content variants: This option prevents sending the same content variant to a recipient that already received it, but includes the recipient for a new content variant.

    When considering which of these two options would be appropriate for a given message, think about how any changes to the drop-ins that are present in the message would affect the overall message. If a drop-in for example makes up the majority of the job's message and the value has changed significantly, then a new content variant would likely not be seen as a duplicate and you can safely choose the "Prevent duplicate messages for same content variants" option, which will check if a recipient has received this specific variant and will send the message again (since it is not a duplicate) if not. If however only a small part of the message at the top or the bottom has changed (like for example an ad banner that is changed dynamically) and the bulk of the message is static, then you may want to choose the "Prevent duplicate messages for job" option because this way, Maestro will suppress sending a variant message to a person who has already received any (variant) message of the job.

    And then there is of course the third option:

    • Allow duplicate messages: This means that duplicate repeated messages to the same recipient are never prevented.

      Choose this option with care: In the majority of cases, users view a duplicate message as annoying. However, there are cases where you may want to actually send duplicate messages. Example: You are offering a summary of the most important guidelines for your organization in the form of a mail job message and you have configured a special web form that users fill out to request this information message. Some users may have already filled out the form and may indeed have received the message, but for some reason have deleted it or have trouble finding it in their inbox. Such a user may want to fill out your request form a second time and would in this case actually expect to receive the same message again, so, in this example, you would configure the job to indeed send duplicate messages.

Time Zone Settings

The option Time zone to be applied to the dates and times specified above allows the choice of which time zone to use when determining what time a job is sent. For example, if the server is located in London (GMT 00:00) and the user is based in New York (GMT -05:00), when the user specifies 10:00 what time will the job be sent? Will it be 10:00 London time or 10:00 New York time?

Note: This setting will not alter the time put into the date of the email. This value is inserted by the SMTP server at the time of delivery and is usually based on local settings. This is not incorrect as it accurately reflects the time the email was actually sent.

About Auto-Repeat Delivery

Jobs with auto-repeat delivery enabled go beyond normal delivery by repeating the job delivery at regular programmable intervals. Various settings control the repeated delivery sequence, which can be used in many ways. Topics to consider for auto-repeat delivery are:

• Specifying the Delivery Times
• Auto-Repeat Delivery together with Dynamic Recipients
• Auto-Repeat Delivery and Content Variants
• Auto-Repeat Delivery and System Shutdown

Specifying the Delivery Times

The delivery times of jobs with auto-repeated delivery are defined as follows:

• The first delivery occurs at the date and time specified in the basic options of the Schedule Delivery page (see above).
• Each subsequent delivery happens a certain amount of time after the previous delivery, which is defined in the advanced options as the Delay interval between repeated deliveries.

Examples:

• If you specify "Immediate Delivery" and a repeat interval of "12 Hours" for the initial delivery and authorize the job at 09:15, then the initial delivery occurs at 09:15, the second one at 21:15, the third one at 09:15 of the next day, and so on.
• If you specify "Deliver at 12:00" and a repeat interval of "24 Hours" (or for the same effect "1 Day"), then you would get one delivery each day, at 12:00.
• If you specify "Deliver at 10:20 on Dec. 6th 2021" (which happens to be a Monday) and a repeat interval of "2 Weeks", then this would cause a subsequent delivery to occur at 10:20 of the Monday of every second week after the initial delivery.
• If you specify "Deliver at 12:00 on Jan. 1st 2022" and a repeat interval of "3 Months", you would get a delivery on the first of each of the months January, April, July, and October resulting in one delivery at the beginning of each quarter.

Auto-Repeat Delivery and System Shutdown

Jobs with auto-repeat delivery do not act like normal jobs if the system is shut down during the scheduled delivery time.

For a normal job, if the system is down at the scheduled delivery time, the job will be delivered immediately after the system is started the next time. The system will recognize that the delivery time of the job has passed while the system was down and will immediately start the delivery to "make up" for the lost time.

This is not true for jobs with auto-repeat delivery. If the system is down at the scheduled delivery time, then the system will recognize that the delivery time has passed while the system was down. Instead of starting delivery immediately, the delivery is re-scheduled to the next available "delivery slot" according to the settings defined when scheduling the job. If there is no such delivery slot available because the end condition for the repeated delivery has already been met, (the threshold time has passed) the job will be marked as failed with a corresponding error message.

Example:

If a job is scheduled to be delivered at 08:00, with an repeat delay interval of "12 hours" (the delivery is supposed to repeat itself at 08:00 and 20:00 of each day), but the system is down at that time, then during the next system startup, the delivery will be re-scheduled from 08:00 to 20:00. Or if the next system startup occurs after 20:00 of that day, the delivery will be re-scheduled to 08:00 of the next day, or even 20:00 of the next day, if necessary, and so on until a delivery time is found that occurs after the system startup. If the job was supposed to stop repeating delivery at a time that has passed before the system startup, the system will not find a "next available delivery time" for re-scheduling. In that case, the job will fail with an according message.

Auto-Repeat Delivery And Dynamic Recipients

Dynamic recipients are the just-in-time variants of recipients defined by text upload or a select from a database, as well as LISTSERV lists, Maestro subscriber lists or recipients selected from a database by LISTSERV. What all these recipient types have in common is that the actual list of recipients a job will be mailed to is determined "just-in-time" at the moment prior to delivery. If such a delivery is performed repeatedly, then each delivery may yield a different list of recipients.

This strategy can be employed in many ways. An example of using dynamic recipients could be sending a generic "Your account balance is negative" warning message, on the 1st of each month, to the recipients who have a negative account balance on that day.

To set up such a job, you would create a job with static content telling the recipients that their account balance is negative (probably using the balance value as a merge field). You would use a recipient definition that is "just-in-time" and that selects exactly those recipients from the database where the account balance is negative. Next, you would schedule this job to be delivered at a certain hour of the first day of the next month, with a repeat interval of "1 Month". After the initial authorization of that first job, the email would automatically go out at the set hour of the 1st of each month, to only the recipients with a negative account balance.

Auto-Repeat Delivery And Dynamic Content Variants

Choosing the "Honor changed drop-in values and create content variants" option for "Handling of Changes to Drop-In Values" prompts Maestro to check for changes of drop-in values each time a repeated delivery is performed.

Any such changed value of a drop-in that is used in the job's HTML or plain content parts means that a new variant of the job's message is created. Each such variant may contain different tracked links, which is why Maestro counts recipients and tracking events for content variants separately.

This powerful feature for example allows you to have a long-running campaign with an ad banner in your message that retrieves its content for example from an external web server. Each time the web server delivers a different banner at the moment when Maestro is scheduled to deliver the auto-repeated job again, this creates a new content variant.

The same logic applies if the drop-in is of the "Text Drop-In" type (so that you edit the value manually from within Maestro): Each change of the value (when encountered at the next scheduled delivery) yields a new content variant that you can report on separately.

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.