Generating Email output

The Email context outputs HTML email with embedded formatting to an email client through the use of an email server. The HTML generated by this context is meant to be compatible with as many clients and as many devices as possible.

Email Output can be generated in two different ways: from the Designer or via Workflow. In both cases, email is sent in a single batch for the whole record set.

To test a template, you can send a test email first.

Output, generated from an Email template, can have the following attachments:

  • The contents of the Print context, in the form of a single PDF attachment. (Compression options for PDF attachments can be specified in the Email context's properties; see Compressing PDF attachments.)
  • The output of the Web context, as a self-contained HTML file.
  • Other files, an image or a PDF leaflet for example.

Attaching the Print context and/or the Web context is one of the options in the Send (Test) Email dialog.

These options are also available in the Create Email Content task in Workflow.

For more information see Email attachments.

Before generating Email output

  • Decide on the use of an Email Service Provider; see Using an ESP with PlanetPress Connect.
  • Make sure that a data set is loaded, that any necessary files, such as images and attachments, are in place, and that the correct settings are selected (see below).
  • If you're using style sheets to style the email, choose whether the styles must be added to the header of the email or to inline style properties as if local formatting was applied (this is also called "embedded CSS"). This setting is made per Email section. See Email section properties.
  • You may want to rasterize certain elements, to ensure that most email clients would actually see the output. Rasterizing converts the element to a JPG or PNG image.
    To rasterize an element, right-click it and select Rasterize options. For a JPG image you can set the quality of the resulting image in a percentage.
    Rasterization options are only available for Boxes (<div> elements); see Boxes.
    A business graphic in an Email section is rasterized by default and output as PNG image, because email clients usually don't support SVG images.
    SVG images in an Email section give an error in the Preflight window (see Doing a Preflight).

  • For Email output, PNG is the preferred image format.
    EPS, PDF, SVG and TIFF images in an Email section are automatically converted to PNG to ensure that they can be seen in the email client.

  • Test and validate the output; see Testing Email output.

Email output settings in the Email context and sections

The following settings for the Email context and Email sections have an impact on how the actual emails are sent.

  • An Email To Script must be available in the template and refer to a valid email address; see Email header settings. If any record does not have a valid email, this record is skipped automatically when generating email output.

    When you send a test email, the Email To Script will not be used; instead, the email will be sent to the address that you specify in the Send Test Email dialog.

  • The sender(s), recipient(s) and the subject can be set using Script Wizards; see Email header settings.
  • Default SMTP settings can be set in the preferences; see Email header settings.
  • If there are multiple Email sections, only one of them can be merged with each record. Make sure that the correct section has been set as the default; see Setting a default Email template for output.
    To dynamically select a section for output, use a Control Script; see Control Scripts.
    When printing from the Designer, the currently open Email section will be outputted.
  • A plain-text version of the HTML is added to each email if this option is checked in the Email section's properties (see Email section properties). With new templates this is always the case.
  • If style sheets are used to style the email, the styles can be added either to the header of the email or to inline style properties as if local formatting was applied (this is also called "embedded CSS"). See Email section properties.
  • PDF attachments can be compressed to make the files smaller; see Compressing PDF attachments.

Testing Email output

It can't be guaranteed that content will look the same in all email clients, particularly when it comes to older client versions, so it is recommended to always test and validate the output by sending a test email.
An example of a tool that can facilitate testing to ensure a consistent look and feel is Litmus: https://litmus.com/email-testing.
If you have a Litmus account, you can enter your Litmus test address when sending a test email (see Generating Email output from Connect Designer).
To narrow down the field of potential email clients by finding out which email clients are most commonly used by your target audience you can use Litmus' analytics tool (see https://litmus.com/email-analytics).

Generating Email output from Connect Designer

To generate Email output from the Designer:

  1. Open a template with an Email context.
  2. Load a data file or database compatible with this template, or open a data mapping configuration. See Loading data.

    If you have an open data mapping configuration and open another data file, the current data mapping configuration will try to retrieve data from the file or database using its own Data Model and extraction logic.

    When generating output with just an open data mapping configuration, the template is merged with the complete sample data file that is part of the data mapping configuration. The output is not limited to the number of records shown in the Data Model pane (which is one of the settings in the DataMapper).
  3. On the File menu, click Send Email or Send Test Email. In the dialog that appears you can, among other things, attach the Print context or the Web context to the email. See Send (Test) Email for a description of all the options. Finally, click OK.

    When you send a test email, the Email To Script will not be used; instead, the email will be sent to the address that you specify in the Send Test Email dialog. If you have a Litmus account, you can enter your Litmus test address. To make the test address appear by default, you can set the default test address in the Email Preferences: select Window > Preferences, click the arrow next to Email, click General and type the test address next to Email Test address.

    See also: Testing Email output.

Generating Email output from Workflow

Here's how to generate Email output from Workflow:

  1. Send the required files to PlanetPress Workflow: the template that contains the Email context, and any data mapping configuration that you want to use to extract data from a data file. See: Sending files to Workflow.
    If the input data is JSON, a data mapping configuration isn't needed.
  2. Create a process in PlanetPress Workflow. See: Email processes with OL Connect tasks.

Aborting content creation

You may want the content creation process to be aborted in certain situations; for example, when a template script fails to load remote content. To abort the content creation process, you may raise a fatal error from within a script in the template; see fatalError(message).

When a script calls this function in Preview mode, the script that triggers it is marked with an error icon in the Scripts pane, and the given message is displayed in a hint.

When generating output from the Designer, the Designer will log the error and display an error dialog with the given message. Content creation is aborted.

When generating output from Workflow, the entire job fails. Workflow will log the error and execute any follow-up actions that are defined in the On Error tab of the respective OL Connect Content Creation task (All in One, Create Email Content, Create Print Content, Create Preview PDF, Create Web Content and Render Email Content). For more information about how to set up follow-up actions, see Using the On Error tab in the Workflow Help.