Email header settings

An email header contains routing information, such as the sender, recipient/s and subject of the message. This topic explains how to customize the header of an email that is generated from an Email template.

The default Email SMTP settings and the sender's name and address are defined in the Connect Designer preferences (see Email preferences). They can be adjusted per run in the Send Email and Send Test Email dialogs.

Email Fields

The subject, the recipients (To, Cc and Bcc), the sender and the Reply to address can be entered in the Email Fields at the top of the workspace. If the fields are not visible, click the words 'Email Fields' (or the small plus before them) to expand the Email Fields area.
To use a variable email address in any of the fields, simply drag and drop a data field into the email field.
The specified subject and addresses will be visible when viewing the email in the workspace in Preview mode.
The To address must always be variable. This field is not used when you send a test email (see Generating Email output).

Note: Using a variable email address requires you to load dataor a data mapping configuration first; see Loading data.

The Email Script Wizard

In addition to the drag and drop method, you can use the Email Script Wizard to add data to an email header field. It lets you choose one or more data fields and enter a prefix and/or suffix (per data field).
There are two ways to open the Email Script Wizard:

  • Via the Email Fields. Open the email section and expand the Email Fields at the top by clicking Email Fields. Click the word before the email field that you want to set. If there already is a script for that field, that script will be opened. Otherwise, a new script will be created and opened.

  • Via the Scripts pane. Click the black triangle on the New button and select the respective email script. A new script will be added to the Scripts pane. Double-click the new script to open it. See Script wizards for an explanation of the options in the script wizard.

The default script adds the content of the selected data field to the header field.
If you want to write a more complex script, click the Expand button. The result of the script should be a valid, fully-formed email address.

The language in which the script has to be written is JavaScript. For more information on writing scripts, see Writing your own scripts.

Other header fields

At some point you may need to define a header field that isn't available in the Preferences or in the Email Fields. This can be done in a Control Script. For a few examples of such scripts, see Adding custom ESP handling instructions. To get started with Control Scripts, refer to Control Scripts.

Email SMTP settings

Simple Mail Transfer Protocol (SMTP) is the standard protocol for sending emails across the Internet.

Default SMTP settings can be specified in the Preferences dialog: select Window > Preferences, expand the Email preferences and click SMTP.

You can add as many presets as needed, for example for different Email Service Providers (see Using an ESP with PlanetPress Connect). To do this, click the Add button at the right. Then fill out the following settings:

  • Name: The name of the preset. This will show up in the Send Email dialog.

  • Host: The SMTP server through which the emails are to be sent. This can be a host (mail.domain.com) or an IP address.

    Tip: Gmail only allows Connect to be used as an SMTP client when "Access for less secure apps" is enabled in the Google account settings.

  • Port: You can specify a port number. This will be added to the host name, for example: smtp.mandrillapp.com:465.

    Tip: If the mail server supports it, the connection will be encrypted without the need to send the server a STARTTLS instruction when port 465 is used.

  • Use authentication: Check this option and fill in the user name if a user name and password are needed to send emails through the host. (The password has to be specified in the Send Email or Send Test Email dialog.)

  • Send STARTTLS: This option is enabled if authentication is checked. With STARTTLS the client negotiates with the mail server to use some form of encryption, usually a version of Transport Layer Security (TLS). Since this improves security it is recommend to enable this option if you use port 25 (the default port), 2525, or 587.
    Note that the email will not be sent if the SMTP server does not support TLS or SSL (an older encryption type).
    This option is ignored when port 465 is used.

When you click the Restore button, the presets for a number of Email Service Providers will appear.

Note: When updating the software from a version prior to version 1.5, pre-existing presets will be maintained in the new version.

In the Send Test Email dialog and Send Email dialog (see Send (Test) Email) you will be able to choose one of the presets and adjust the settings to your needs.

Subject

To specify a subject for an email template:

  1. Open the email section and expand the Email Fields by clicking Email Fields at the top of the section.

  2. Type the subject in the Subject field.

To add variable data to the subject of an email section, drag and drop a data field into the Subject field at the top of the workspace. Two things will happen:

  • A placeholder for the data field appears in the subject line (for example: @email@).
  • A new script, named Subject, is added to the Scripts pane.

You can add as many data fields to the subject as you like. When you do add more than one data field, the existing Subject script will be modified to include all data fields that are added to the subject.

The result of the script will be visible in the Subject field in Preview mode: click the Preview tab at the bottom of the workspace.

Note: By default, the Subject script targets one email section specifically. You can see this when you double-click the script on the Scripts pane. The selector of the Subject script contains the name of a particular email section, for example: html.HTML_EMAIL[section="Content"] (in this case, Content is the name of the email section). If you remove the [section=...] part from the selector, the script will work for all email sections.

Subject scripts made with versions of the software prior to version 1.7 are not specific to one email section.

Writing a custom Subject script

The default script replaces all @field@ placeholders in the subject line with field values. This script can be modified, for example to create a subject that depends on the value of a data field. Open the Script Wizard (see The Email Script Wizard), click the Expand button and modify the script.
If you don't know how to write a script, see Writing your own scripts first.

Note: A Subject script created by clicking Subject in the Email Fields always targets one email section specifically, for example: html[section="Content"] (in this case, Content is the name of the email section). Remove the [section=...] part from the selector of the script to make the script work for all email sections.

Recipients: To, CC and BCC

To specify recipients for Email output, you can simply drag and drop a data field that contains an email address into the To field at the top of the workspace. A new script, named To, will be added to the Scripts pane.
Note that you can add only one data field to the email field this way. When you drag another data field into the email field the existing script will be replaced.

Alternatively, you could use the Script Wizard to create the scripts; see The Email Script Wizard.

Email addresses can be added to the Cc and Bcc fields in the same manner, but it is also possible to type an email address directly in the Cc or Bcc field (as long as no script is present for that field). Email addresses in the Bcc ('blind carbon copy') field will not be visible to any other recipient of the email.

For each recipient, a name and email address can be specified. In that case the email address itself must be enclosed in <>, for example: Tester <tester@example.com>. The name can be enclosed in quotes: "Tester" <tester@example.com>. If the recipient's name has a comma, it should always be enclosed in quotes: "Tester, QA" <tester@example.com>.

Separate multiple email addresses using a semicolon or a comma.

Sender

From address

A default From name and email address can be specified in the Preferences dialog: select Window > Preferences, expand the Email preferences and click General.
This name and email address will appear as the default in the Send Email and Send Test Email dialogs (see Send (Test) Email).

The default can be overwritten by typing an email address directly in the From field (as long as no script is present for this field).

Using the Script Wizard you can create a dynamic From address; see The Email Script Wizard. It is also possible to drag and drop one data field into the From field directly.

Tip: A dynamic From address is often used when sending email campaigns and to do tracking of email replies. Include the recipient's email address in a dynamic From address to enable automatic detection and removal of undeliverable e-mail addresses. (This technique is called VERP; see Wikipedia.)

Note: When sending emails with a variable From address through PlanetPress Workflow, check the option Precedence to template address in the Create Email Content task properties to make sure that the dynamic address gets precedence over the email address specified in the task properties (see Create Email Content task).

Reply To address

The Reply To address is used by mail clients, when the recipient clicks the Reply To (or Reply All) button.

You can type an email address directly in the Reply To field (as long as no script is present for this field).
Alternatively, you can drag and drop one data field into the field, or use the Email Script Wizard (see The Email Script Wizard), to specify the Reply To address in a script.

Meta information

Meta information in an email is not visible to the receiver, but might have an effect on the representation of the email in the e-mail client.

To add custom meta information to an email:

  1. Right-click the email section on the Resources pane and select Properties....

  2. The Meta Information group lists all <meta> tags that will be added to the email. Click the Add button to add a new <meta> tag to the list.

  3. Select the type of <meta> tag, which is either name or http-equiv.

  4. For a name-type meta tag, enter the value.

  5. Enter the content.

Example: When you add a name meta tag with the value viewport and content width=320, the following will be added to the email:
<meta name="viewport" content="width=320">.

For more information on <meta> tags, see MDN Web Docs - meta.

Email PDF password

The Email PDF Password Script Wizard defines a password with which to protect the PDF generated when using the Print context as PDF Attachment option in the Send Email or Send Test Email dialogs (see Generating Email output). The result of the script will be the password necessary to open the PDF when it is received by email.

To define a password to protect the generated PDF attachment:

  1. On the Scripts pane, click the black triangle on the New button and click Email PDF password Script. A new script is added to the Scripts pane.

  2. Double-click the new script to open it.

  3. Select a data field and optionally, type a prefix and/or suffix.

Password types

PDF allows for two types of passwords to be set on a secured PDF file: a user password and owner password. The user password allows a limited access to the file (e.g. printing or copying text from the PDF is not allowed). The owner password allows normal access to the file. The Email PDF password script sets both the user and owner password to the same value, so that when the recipient provides the password, he can manipulate the file without limitations.

Note: If a template has a Control Script that creates multiple PDF attachments, all the attachments are secured by the same password.

Note: Via a Control Script it is possible to set a different user password and owner password, see Control Script: Securing PDF attachments, Control Scripts and Control Script API.