Import and install the extension using the Extension Manager.

You may be required to install extension Address list (tt_address) which is  a prerequisite of extension Direct Mail.

Some updates to the database structure may be needed. Press the “Make updates” button to make these updates.

When the extension is installed, a “Direct Mail” item will appear in the Web section of the backend menu, provided that the user is granted access using the User Admin tool.

The Extension Manager installation dialog allows to set the following extension configuration variables:

If you are upgrading to version 2.0+ from an earlier version, an additional entry may be presented in the function drop-down menu of the extension manager: UPDATE! This option provides a function to convert some tables of your database. You should read the section below about upgrading to version 2.0+.

All operations of the Direct Mail module are performed from a specifically configured SysFolder. You may configure multiple Direct Mail folders.

To create a Direct Mail folder:

Once the Direct Mail folder is created, its title should appear in the list of available Direct Mail folders when using backend menu option Web > Direct Mail. Clicking on the folder title should display a page with the module drop-down function menu.

The Direct Mail configuration properties are set in the Page TSConfig of the Direct Mail folder under key mod.web_modules.dmail.

Note that all these properties may conveniently be set using the Direct Mail module function “Module configuration”.

The following properties set default values for corresponding properties of direct mails. These properties of direct mails determine the headers inserted in the direct mail messages.

The following properties set default values for corresponding properties of direct mails. These properties of direct mails determine the format of the content of direct mail messages.

The following properties set default values for corresponding properties of direct mails. These properties of direct mails specify parameters used to fetch the content of the direct mails.

The following properties specify the content transfer encodings and character sets to use when sending mails.

The following properties specify how links in mail content are processed.

The following properties specify parameters for the operations of various functions of the Direct Mail module.

Newsletter pages are just normal pages. Their rendering is configured by the TS template. However, take the following into consideration:

It is good practice to always include a plain text version in email messages. Some email clients are not able to present the html content of email messages, but will present the plain text version if available. Users of many email clients may also have the option to set their preference as to the format that they wish to see.

In order to configure the rendering f your newsletter pages in plain text, include static template “Direct Mail Plain Text” on the TS Template applicable to the pages. This static template contains a pre-defined template for plain text content rendering and makes it accessible as page type 99. You may thereafter configure the template to your needs in the template.

Note: In versions previous to version 2.0, plain text rendering was achieved by including static template "plugin.alt.plaintext (99)". This static template may still be used in version 2.0+.

The “Direct Mail Plain Text” static template is as follows:

Constants

plugin.tx_directmail_pi1 {

    # cat=plugin.tx_directmail_pi1/file; type=file[html,htm,tmpl,txt]; label= Template File for plain text version: &type=99 defines plain text rendering for page content.

  file.template = EXT:direct_mail/pi1/tx_directmail_pi1_plaintext.tmpl

    # cat=plugin.tx_directmail_pi1//; type=string; label= Site url: Enter the url of the site here.

  siteUrl = http://www.example.test/

    # cat=plugin.tx_directmail_pi1/enable/; type=boolean; label= Use flowed format: The same option should be set on the direct mail.

  flowedFormat = 0

}

Setup

plugin.tx_directmail_pi1 = USER

plugin.tx_directmail_pi1.userFunc = tx_directmail_pi1->main

plugin.tx_directmail_pi1 {

  siteUrl = {$plugin.tx_directmail_pi1.siteUrl}

  flowedFormat = {$plugin.tx_directmail_pi1.flowedFormat}

  header.defaultType = 1

  header.date = D-m-Y

  header.datePrefix = |###HEADER_DATE_PREFIX### |

  header.linkPrefix = | ###HEADER_LINK_PREFIX### |

  header.1.preLineLen = 76

  header.1.postLineLen = 76

  header.1.preBlanks=1

  header.1.stdWrap.case = upper

  header.2 < .header.1

  header.2.preLineChar=*

  header.2.postLineChar=*

  header.3.preBlanks=2

  header.3.postBlanks=1

  header.3.stdWrap.case = upper

  header.4 < .header.1

  header.4.preLineChar= =

  header.4.postLineChar= =

  header.4.preLineBlanks= 1

  header.4.postLineBlanks= 1

  header.5.preBlanks=1

  header.5.autonumber=1

  header.5.prefix = |: >> |

  defaultOutput (

|

[###UNRENDERED_CONTENT### ###CType### ]

|

  )

  uploads.header = |###UPLOADS_HEADER###|

  images.header = |###IMAGES_HEADER###|

  images.linkPrefix = | ###IMAGE_LINK_PREFIX### |

  images.captionHeader = |###CAPTION_HEADER###|

  bulletlist.0.bullet = |*  |

  bulletlist.1.bullet = |#  |

  bulletlist.2.bullet = | - |

  bulletlist.3.bullet = |>  |

  bulletlist.3.secondRow = |.  |

  bulletlist.3.blanks = 1

  menu =< tt_content.menu.20

  shortcut =< tt_content.shortcut.20

  shortcut.0.conf.tt_content =< plugin.tx_directmail_pi1

  shortcut.0.tables = tt_content

  bodytext.stdWrap.parseFunc.tags {

    link =< lib.parseFunc_RTE.tags.link

    typolist = USER

    typolist.userFunc = tx_directmail_pi1->typolist

    typolist.siteUrl = {$plugin.tx_directmail_pi1.siteUrl} 

    typolist.bulletlist =< plugin.tx_directmail_pi1.bulletlist

    typohead = USER

    typohead.userFunc = tx_directmail_pi1->typohead

    typohead.siteUrl = {$plugin.tx_directmail_pi1.siteUrl}

    typohead.header =< plugin.tx_directmail_pi1.header

    typocode = USER

    typocode.userFunc = tx_directmail_pi1->typocode

    typocode.siteUrl = {$plugin.tx_directmail_pi1.siteUrl}

  }

}

includeLibs.tx_directmail_pi1 = EXT:direct_mail/pi1/class.tx_directmail_pi1.php

tx_directmail_pi1 >

tx_directmail_pi1 = PAGE

tx_directmail_pi1.typeNum=99

tx_directmail_pi1.config.disableAllHeaderCode = 1

tx_directmail_pi1.10 = TEMPLATE

tx_directmail_pi1.10 {

  template = FILE

  template.file = {$plugin.tx_directmail_pi1.file.template}

  marks.CONTENT < styles.content.get

  marks.CONTENT.renderObj = < plugin.tx_directmail_pi1

  marks.DATE = TEXT

  marks.DATE.data = date:U

  marks.DATE.strftime = %e. %B %Y

}

tx_directmail_pi1_test < tx_directmail_pi1

tx_directmail_pi1_test {

  wrap = <pre>|</pre>

  typeNum=199

  config.no_cache=1

}

If you insert News records in your newsletter page, using the “Insert records” content element type, you may configure the plain text rendering of these News rendering. Simply add static template “Direct Mail News Plain Text” in your TS template. Note that order is important: “Direct Mail News Plain Text” should come after or below “Direct Mail Plain Text”. You may then tailor the template to your specific needs.

The “Direct Mail Plain Text” static template is as follows:

Setup

plugin.tx_directmail_pi1 {

  shortcut.0.conf.tt_news =< plugin.tt_news

  shortcut.0.conf.tt_news.code = PLAINTEXT

  shortcut.0.conf.tt_news.defaultCode = PLAINTEXT

  shortcut.0.conf.tt_news.displayCurrentRecord = 1

  shortcut.0.conf.tt_news.plainTextConf < plugin.tx_directmail_pi1

  shortcut.0.tables = tt_content,tt_news

  tt_news_author.defaultType = 3

  tt_news_author.date = D-m-Y

  tt_news_author.prefix = |###TT_NEWS_AUTHOR_PREFIX### |

  tt_news_author.datePrefix = |###TT_NEWS_AUTHOR_DATE_PREFIX### |

  tt_news_author.emailPrefix = | ###TT_NEWS_AUTHOR_EMAIL_PREFIX### |

  tt_news_author.1.preLineLen = 76

  tt_news_author.1.postLineLen = 76

  tt_news_author.1.preBlanks=1

  tt_news_author.1.stdWrap.case = upper

  tt_news_author.2 < .tt_news_author.1

  tt_news_author.2.preLineChar=*

  tt_news_author.2.postLineChar=*

  tt_news_author.3.preBlanks=1

  tt_news_author.3.stdWrap.case = upper

  tt_news_author.4 < .tt_news_author.1

  tt_news_author.4.preLineChar = =

  tt_news_author.4.postLineChar = =

  tt_news_author.4.preLineBlanks= 1

  tt_news_author.4.postLineBlanks= 1

  tt_news_short < .bodytext

  tt_news_short.header = |###TT_NEWS_SHORT_HEADER### |

  tt_news_bodytext < .bodytext

  tt_news_bodytext.header = |###TT_NEWS_BODYTEXT_HEADER### |

}

If you intend to make use of Direct Mail categories, you should do the following.

First, add static template “Direct Mail Content Boundaries” to the TS template of the Direct Mail folder. This will ensure that content boundaries are inserted on the page when it is rendered whenever categories assignments are found on the content elements of the page. The static template ensures that content boundaries will be inserted in both HTML and plain text content. Insertion of boundaries is specified by setting TS setup property:

config.insertDmailerBoundaries = 1

This setting is already included in static template  “Direct Mail Content Boundaries” .

Secondly, categories that may be assigned to content elements, to address records, to FE users or to recipient lists are determined by Page TSConfig. Therefore, you should configure the following properties in the Page TsConfig of the Direct Mail folder and, perhaps, of any page whose subtree may contain records of the corresponding types and which may be used in Direct Mail operations:

TCEFORM.tt_content.module_sys_dmail_category.PAGE_TSCONFIG_IDLIST = pid_list

TCEFORM.tt_address.module_sys_dmail_category.PAGE_TSCONFIG_IDLIST = pid_list

TCEFORM.fe_users.module_sys_dmail_category.PAGE_TSCONFIG_IDLIST = pid_list

TCEFORM.sys_dmail_group.select_categories.PAGE_TSCONFIG_IDLIST = pid_list

where pid_list is the list of page id's on which categories may be found that may be assigned to records of the given type.

Finally, when the use of categories is thus configured on a page and its subtree, you may also want the categories assignment field to be displayed in backend forms. This is achieved by setting the following properties in Page TSConfig of the same pages:

TCEFORM.tt_content.module_sys_dmail_category.disabled = 0

TCEFORM.tt_address.module_sys_dmail_category.disabled = 0

TCEFORM.fe_users.module_sys_dmail_category.disabled = 0

TCEFORM.sys_dmail_group.select_categories.disabled = 0

The “Direct Mail Content Boundaries”  static template is as follows:

Setup

 // Configuring the insertion of dmailer boundaries

includeLibs.tx_directmail_container = EXT:direct_mail/res/scripts/class.tx_directmail_container.php

// In html content

tt_content.stdWrap.postUserFunc = tx_directmail_container->insert_dMailer_boundaries

// In old plaintext content static tenmplate

lib.alt_plaintext.renderObj.userProc < tt_content.stdWrap.postUserFunc

lib.alt_plaintext.renderObj.userProc.useParentCObj = 1

// In new direct mail plain text plugin

plugin.tx_directmail_pi1.userProc < tt_content.stdWrap.postUserFunc

plugin.tx_directmail_pi1.userProc.useParentCObj = 1

// Enable the insertion of content boundaries

config.insertDmailerBoundaries = 1

To enable the click statistics of the Direct Mail module, enable the following checkbox in the "Module configuration” function:

This will register all links in the email messages and count all clicks on them.

Note that form url's are not directed through the jumpurl feature but rather directly to the target page.

A nice trick is to place a little clear-gif image in your HTML template and put the parameter dmailerping=”1” in the tag. This will force the capture function to set the url of this image absolute through the jumpurl registration. This means in other words that when this mail is opened it will be registered. This is an additional feature to the regular feature which registers all links clicked in the mail.

Example:

<img src="typo3conf/ext/direct_mail/res/gfx/dmailerping.gif" width="1" height="1" dmailerping="1" />

Note that the result of the jumpurl setting on the above HTML line is that the src attribute will be replaced by one that refers to the address of a script. Such attribute in HTML content of email messages may be disabled by SPAM filtering software.

User TSConfig and Page TSConfig may be used to control access to the functions of the Direct Mail module. Using the Typo3 User Admin Tool, access rules may be specified for any particular BE user or BE user group. Properties of User TSConfig are documented in this document: http://typo3.org/documentation/document-library/doc_core_tsconfig/User_TSconfig/

mod.web_modules.dmail.menu.dmail_mode.[function]

The mailer engine may be invoked from the Direct Mail backend module. However, if your newsletters are sent to numerous recipients, this extension provides a mailer engine script that may be configured as a cron task on the server. In this example setting, the mailer engine will be invoked every 5 minutes and will check if any mails need to be sent:

*/5 * * * * /home/....../public_html/typo3conf/ext/direct_mail/mod/dmailerd.phpcron> /dev/null

*/5 * * * * /home/....../public_html/typo3/ext/direct_mail/mod/dmailerd.phpcron> /dev/null

Note that the absolute path to the script must be specified.

Note also that dmailerd.phpcron is a shell script and requires the availability of a PHP binary, "/usr/bin/php”. Depending on your server configuration, you may have to edit the first line of the script to refer to the location of the PHP binary.

The following option applies only when Sendmail is used in Unix/Linux environments.

When sending a large number of emails with the mailer engine, processing delays may be caused by attempts on the part of the mail server to locate the destination domain of each email. As a consequence, timeouts may occur causing failure of the cron ask. Or the cron task may be triggered before the previous instance has terminated. In the latter case, some emails may be sent multiple times.

Such problems may be avoided by using the Sendmail deferred delivery mode. In this mode, each email is simply put on a queue for later processing by Sendmail. This results in much faster response to the cron task.

You may enable the deferred delivery mode by setting the corresponding variable on the installation screen of this extension. The option applies only to emails sent by the mailer engine cron task of the Direct Mail extension.

The following variables must be set in the Sendmail configuration file (values shown here are just examples):

DAEMON=yes

SMQUEUE=10m

QUEUE=30m

These example settings have the following meaning: the email queue will be emptied every 10 minutes. If a problem is encountered while trying to send an email, it will be put on another queue and delivery will be attempted again every 30 minutes.

For more information on Sendmail configuration, see: http://www.sendmail.org/.

There are probably many ways to configure analysis of returned mails. We propose an approach based on open Source program fetchmail. For more information about fetchmail, see The fetchmail home page .

-rwx--x---  1 root root 208 Jun 20 12:50 /root/.fetchmailrc

poll my.pophost.org timeout 40 username "username-of-popbox" password "password-of-popbox" flush mda "/path/to/your/TYPO3/installation/typo3conf/ext/direct_mail/mod/returnmail.phpsh"

*/10 * * * * fetchmail> /dev/null

The two main considerations when upgrading to version 2.0+ from a previous version are:

When upgrading to version 2.0+, it is necessary to convert pre-existing categories in Page TSConfig and create corresponding Direct Mail Categories in the Direct Mail folders. If any categories were assigned to Content elements, Addresses , FE Users or Recipient Lists, these assignments also need to be converted to refer to the newly created Direct Mail Categories.

Conversion of categories is NOT revertible. Therefore, it would be prudent to take a backup of the TYPO3 database before this conversion is performed.

When upgrading to version 2.0, an additional option is presented in the function drop-down menu of the Extension Manager: UPDATE! The additional option is presented if a Direct Mail folder already exists and until at least one Direct Mail Category has been created.

If you select the UPDATE! option, pre-existing categories defined in Page TSConfig will be converted into new Direct Mail Categories. The Direct Mail categories will be created in each of the Direct Mail folders for which category definitions may be found in Page TSConfig.

Conversion of categories assignments in Content elements, Addresses, FE Users and Recipient Lists will also be attempted. If the use of categories was not yet configured, this part of the conversion process will fail, but may re-attempted a later time, using the “Categories conversion” function of the Direct Mail module. The next step is thus to configure the use of categories: see the section of this document on this subject.

Note that the conversion of categories assignments is only simulated, until you effectively confirm the conversion.  Once confirmed, the records are updated and the conversion cannot be undone without restoring the table with some database backup.

When the use of categories is configured, you may re-attempt the conversion of categories assignments using the “Categories conversion” option of the function menu of the Direct Mail module. The function will report statistics on the conversion being performed, as well as conversion already done. It will also list the records that could not be converted: this exception would normally be due to the fact that the use of categories is not configured for this type of record in the page subtree in which it is found.

Although it may not be undone, categories conversion may be re-attempted as many times as required without causing any harm.