Drop-In Content

What is Drop-In Content?

Drop-in content is similar to text merging, where the same content is merged into the email message for all recipients.

The value by which a drop-in is replaced can either be user-defined (as explained here) or can be system defined (for system drop-ins).

Drop-ins can be used to create pre-defined content parts that can then be inserted into any message. For example, you could create drop-in content elements with your official company header and footer, and then easily add these to all your messages, simply by including their names in the content.

Drop-in content types that derive their text from an external source (for example, a file or a URL, see below), can also be used to create content that is inserted into the message at the moment of sending. This "just-in-time" content may be unknown at the time the message itself is defined. For example, you might create a drop-in that retrieves a stock quote from a certain URL. If you then create a message with that drop-in and schedule the email delivery for a future time, you will be sure that the most current stock quote is merged into the mail, and not the quote from the moment you created the content (or authorized the sending). This method ensures that your stock quote will always be up-to-date.

To include a drop-in content element into a message, simply type the drop-in element's name (with the exact spelling and case) and surround it with the opening and closing tags you have defined. This is called a "drop-in placeholder". For example, if you have a drop-in element with your company header, which you called "corp-header" (without the quotes), and you have defined the opening and closing tags "{{" and "}}", then you would include the placeholder "{{corp-header}}" into your content. This text would then be replaced whatever content you defined for your header in the body of the message.

You can define plain-text drop-in elements that can be included in any kind of content. HTML drop-ins can only be included in HTML content.

In the email message itself, the replacement of the placeholders with the actual drop-in element content happens just before the email is sent. You can define your message content, with all placeholders, at one time, and then schedule the email to be sent at a future date. The placeholders will not be replaced at the moment of scheduling, but just before sending, on the scheduled date and time. At that time, LISTSERV Maestro will determine the content of all drop-in elements it finds and will insert the content of the drop-ins, replacing the placeholders.

On the landing pages, the drop-in replacement happens at the moment the landing page is displayed in the recipient's browser or when the PDF landing page is downloaded. This replacement on the landing page happens anew each time the page is displayed (or downloaded). This has the effect, that if the content of the drop-in changes, then any subsequent access to the landing page will show the new content. This is true both for just-in-time drop-ins that get their content from a file, URL or a database, as well as for simple text drop-ins where the content is defined in Maestro itself. And this of course means that if a drop-in is later deleted, then from then on it will no longer be replaced when the landing page is viewed (but it is possible to create a new drop-in with the same name, so that the drop-in is once again replaced correctly on the landing page).

User-Defined Drop-In Element Types

There are four different types of drop-in elements available, all of which derive their content from a different kind of internal or external source:

Text: The content of the drop-in element is derived from a static text that is defined by the user at the time of the creation of the drop-in. The placeholder will be replaced with this static text.
File: The content of the drop-in element is loaded from a text file that is accessed by a file name that is defined by the user at the time of the creation of the drop-in. The placeholder will be replaced with the text that is found in this file exactly at the moment of the delivery. The file itself must be accessible from the server; it can not be a local file but rather a file available in the file system of the server.
URL: The content of the drop-in element is loaded from a text file that is accessed by an http:// or ftp:// URL defined by the user at the time the drop-in is created. The placeholder will be replaced with the text that is found in this file exactly at the moment of delivery. The URL must be a URL that is accessible from the server, by the given protocol (http:// or ftp://). In some cases, for example, if firewalls are involved, a URL may not be accessible from the server even though it is accessible from the workstation of the user accessing Maestro. Keep in mind that this URL needs to be accessible from the server.
Database: The content of the drop-in element is queried from a database. The database connection settings and the SQL select statement used for the query are defined by the user at the time the drop-in is created. The query is executed at the moment of replacement, and the content of the first column in the first row of the result set is converted to a text, which is then used to replace the placeholder.

File-type or URL-type drop-ins of the HTML type may also contain HTML tags that insert images into the text (<img> tags) with a file name. The corresponding image will then be loaded and sent as part of the message, as an "inline-image". In this case, access to the image file/URL must have been allowed by the administrator, just as for the text file of the drop-in itself (see below).

To embed an inline image into a file-type or URL-type drop-in, simply include the image's file name as a relative path (relative to the location of the drop-in page), for example <img src="images/sample.gif">. For file-type drop-ins, you may also include the image's file name as an absolute path (in Windows this would include the drive-letter), but then you need to remember to include the "file://" protocol, for example: <img src="file://C:\sample\images\sample.gif">.

Image tags that reference images by absolute Web URLs are possible too, and can be used in any drop-in of the HTML type. Images that are embedded by absolute Web URLs (usually starting with http://) are not sent along with the email as inline images; instead, they are sent as "linked images", meaning that the sent email will contain only references to the images on the Web.

Drop-In Element Recursion or Nested Drop-ins

The text of a drop-in element (no matter the source from which it is derived) may in turn contain placeholders with the names of other drop-ins. Before a placeholder is replaced by the matching drop-in's text, that text is first scanned for further placeholders. If any are found, then they are replaced first. If during these replacements further nested placeholders are found, then they are replaced too, and so on, until no more placeholders need to be resolved.

When using nested drop-in placeholders, be careful not to create an endless recursion by using the name of the placeholder within the content of the drop-in. A drop-in may not contain its own placeholder name. Similarly, recursive loops, like "A contains B and B contains A" (or even longer loops with several nested drop-ins), are not allowed. If during the chain of nested drop-in replacements a drop-in is encountered that has already been replaced earlier in the same chain, then Maestro will generate an error and your email job will not be delivered.

Testing Drop-Ins

Depending on the type of a drop-in or how its content is defined, there are several circumstances that may make the replacement of a drop-in fail:

If the drop-in contains other drop-ins in a nested endless recursion loop, then the replacement will fail.
If a drop-in is of the HTML type, but is included either in a plain text message or in the alternative text of an HTML message, then the replacement will fail.
If a file-type drop-in is defined with a file name for which no file can be found on the server (or the file is not accessible for some other reason), then the replacement will fail.
If a URL-type drop-in is defined with a URL that is not accessible from the server, then the replacement will fail.
If a database-type drop-in is defined with database connection parameters that cannot be used to connect to a database, if the database is down, or if the SQL query does not result in at least one row with at least one column, then the replacement will fail.

Because of these circumstances, and because you will want to preview what your drop-in looks like, all drop-in definition screens contain an option to test the current drop-in. This will display the content of the drop-in at the moment of the testing, with all nested drop-ins (if any) resolved. If the drop-in replacement has failed, then an error message will be displayed.

Multiple Drop-Ins

You may use any number of drop-in placeholders in the email content or in the text of other drop-ins.

You may even use the same drop-in placeholder several times in the same content (although not in a way that would lead to an endless recursion loop, see above), or even in different parts of the same message (for example the HTML part and the alternative text part of an HTML message).

If the same drop-in placeholder is used several times in the same message, all occurrences of this placeholder will be replaced with exactly the same text. The source that defines the drop-in will be accessed only once, and the result will be used to replace all placeholders of the same name for the entire message.

Access Restrictions

Before using a file-type or URL-type drop-in, the system administrator will need to configure certain files, folders, and/or URLs on the server and make them available to use with drop-ins and accessible to you. This configuration is to prevent security breaches to the system. To access a file on the server without any security measures would open the possibility for access to confidential files on the server and include their content in a message. Similarly, accessing a URL from the server could allow access to URLs (for example, on an intranet) that are normally not accessible (for example, they are protected by a firewall, but the server is behind this firewall).

To help avoid such security holes, Maestro, by default, does not allow you to define working file-type or URL-type drop-ins until the administrator configures the files, folders, and URLs associated with them. If you are experiencing difficulty with these two drop-in types, then check with your system administrator.