DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

Configuration Reference

Target group: Developers

This reference manual does not cover all possible configurations of this extension. To help you and others learn and share your newsletter configurations we have enabled the project wiki on GitHub for public contribution.

Scheduler and Mail Transport

  1. If not done already, set up TYPO3 Sheduler. See Scheduler documentation
  2. Within Scheduler, schedule the task to send newsletters, and optionally to fetch bounced emails
  3. Configure mail transport in LocalConfiguration.php (more info in API documentation):
<?php

return [
    'MAIL' => [
        'transport' => 'smtp',
        'transport_smtp_server' => 'smtp.example.com:587',
    ],
];

Recipient Lists

There is several ways to define a list of recipients. Those are:

  • SQL: specify SQL queries to fetch data from any table with at least an ‘email’ field
  • BE-users: select existing backend users
  • FE-Groups with FE-Users: select frontend groups containing frontend users
  • Page with FE-Users: select pages where frontend users are stored
  • CSV file: upload a CSV file containing users
  • CSV list: specify CSV content (eg: copy/paste from a file)
  • CSV url: specify an URL to fetch a CSV file from
  • HTML: fetch an URL and parse its content to find emails

SQL recipient lists are, by far, the most flexible and powerful way do define a list of recipients. It allows the dynamic composition of strings that can be used in newsletter content. And it also allows you to take action (SQL queries) upon specific events (bounced email, unsubscribe). Thus we strongly recommend the use of SQL Recipient List and to read the [[Recipient_List_SQL_Examples]].

For CSV, when asked for CSV Fields, you should enter the column names, eg: email,firstname,lastname. Then file/list/url should only contains the values without any column headers, eg: me@example.com,John,Connor.

You can define a storagePid in the Constants if you want different Recipient Lists for different Users. Otherwise every User can use every Recipient List.

Special fields

Recipient List can include as many fields as needed to compose the newsletter, but there are a few reserved fields that have a special meaning:

Field Mandatory Type Description Default
email string Recipient email  
plain_only   bool Whether to send only plain text The Recipient List value
L   int Language code of content The Recipient List value
sender_email   string Sender email The Newsletter value
sender_name   string Sender name The Newsletter value
replyto_email   string Reply-To email The Newsletter value
replyto_name   string Reply-To name The Newsletter value

Bounce Accounts

A new record type called “Bounce account”. You should select a bounce account for newsletter. The bounce account is used in two ways:

  • To provide an email address for the mail to bounce to (“Return-Path:” header)
  • To provide login information to the email account for the bounce-system to login to.

Once a newsletter has a BounceAccount and the bounce Scheduler task is enabled, the extension Newsletter will automatically attach the address as return-path, read the rejected emails and disable/delete the failed email addresses. The bounced emails will also appear in the statistics.

The bounce account is accessed via fetchmail. It is possible to add your own fetchmail configurations to the bounce account. The Fetchmail Configuration field supports 5 marker substitutions:

  • ###SERVER### Domain of the bounce account email server.
  • ###PROTOCOL### Connection protocol of the email server (IMAP|POP3).
  • ###PORT### Connection port of the bounce account email server.
  • ###USERNAME### Username for the bounce account.
  • ###PASSWORD### Password for the bounce account.

A simple default configuration is automatically supplied when you create a new bounce account in the Typo3 Backend, however this simple configuration does not support encrypted TLS/SSL connections. Encrypted connections are required for connecting to popular email providers such as Google Gmail. Such configurations are beyond the scope of this manual. For more information on writing fetchmail configurations please consult the fetchmail (1) man pages or the internet.

You can define a storagePid in the Constants if you want different Bounce Accounts for different Users. Otherwise every User can use every Bounce Accounts.

Unsubscription Notifications

Unsubscription should be automated, for example via proper configuration of SQL for bounced email. However it is possible to receive an email whenever a recipient requests for unsubscription. The “Notification email” field needs to be specified in extension configuration (in Extension Manager) or via template TypoScript.

TypoScript Reference

The extension configuration is set globally via the Extension Manager, but it can be overwritten by TypoScript setup. In TypoScript setup the configurations must be prefixed with module.tx_newsletter.

Config Description Type Default
view.templateRootPath Path to template root (BE) string EXT:newsletter/Resources/Private/Templates/
view.partialRootPath Path to template partials (BE) string EXT:newsletter/Resources/Private/Partials/
view.layoutRootPath Path to template layouts (BE) string EXT:newsletter/Resources/Private/Layouts/
config.sender_name

Default sender name.

Can be overridden for each newsletter. If “user”, the be_user owning the newsletter will be used. If blank, will default to the site name from $GLOBALS[‘TYPO3_CONF_VARS’][‘SYS’][‘sitename’]. Otherwise can be any string.

string user
config.sender_email

Default sender email.

Can be overridden for each newsletter. If “user”, the be_user owning the newsletter will be used. If blank, will default to generic settings for the site or the system. Otherwise must be a valid email address.

string user
config.replyto_name

Default Reply-To name.

Can be overridden for each newsletter. Can be any string.

string  
config.replyto_email

Default Reply-To email.

Can be overridden for each newsletter. If blank, will not be set. Must be a valid email address.

string  
config.notification_email

Notification email.

Specify a valid address email to receive notification when recipients unsubscribe. If “user”, the be_user owning the newsletter will be used. If blank, no notification will be sent. Otherwise must be a valid email address.

string user
config.fetch_path

Base URL (scheme + domain + path) from which to fetch content and encode links with.

Leave blank to use domain-records from the page tree.

string  
config.append_url

String to append to URL’s when fetching content.

For example use &type=<num> allows you to implement your newsletter with a special template. Or disable cache with &no_cache=1.

string  
config.path_to_lynx

Path to Lynx text web browser.

This program is not required, but can be used by Newsletter to produce an acceptable plaintext conversion.

string /usr/bin/lynx
config.path_to_fetchmail

Path to fetchmail program.

This a standard unix mail-retrieval program. It is used to collect bounced emails with.

string /usr/bin/fetchmail
config.keep_messages

Keep bounced emails on server.

Checking this option will leave bounced emails on the server. Default behaviour is to delete bounce messages, once they have been processed.

boolean 0
config.attach_images

Attach inline images to newsletters.

Leave this checked to enable attached, inline images. This will normally improve you viewers experience, but reduces the performance of the mailer, since it has to deliver much more (binary) data. Uncheck it to instead link to the images online.

boolean 1
config.mails_per_round

Number of mails to send per iteration.

This can be used to limit the rate on which Newsletter will send out mails. You must set this if you wish to use the “Invoke mailer” button. If you specify 0 as value, it will send all mails in one go.

integer 100
config.unsubscribe_redirect

Redirect to an external URL or internal Typo3 page.

When set to a valid URL or a numeric Page ID (pid) the user will be redirected to that location instead of the default rendering of the unsubscribe template.

string  
config.no-track

A no-track marker.

A unique marker or keyword that can be added to links in your newsletter to exclude them from being tracked when ‘Detect clinked links’ is enabled. How you add the marker to your anchor links is up to you.

string  

RealURL

It is possible to configure the extension for use with RealURL to shorten the length of URLS inside your newsletters.

Here is a example trimmed from realurlconf.php:

<?php
$TYPO3_CONF_VARS['EXTCONF']['realurl']['_DEFAULT'] = [
    // ...
    'postVarSets' => [
        '_DEFAULT' => [
            // RealURL for newsletter extension
            'redirect' => [
                [
                    'GETvar' => 'type',
                    'valueMap' => [
                        'z' => '1342671779',
                    ],
                ],
                [
                    'GETvar' => 'tx_newsletter_p[action]',
                    'valueMap' => [
                        'g' => 'clicked',
                        's' => 'show',
                        'u' => 'unsubscribe',
                        'o' => 'opened',
                    ],
                ],
                [
                    'GETvar' => 'tx_newsletter_p[controller]',
                    'valueMap' => [
                        't' => 'Link',
                        'e' => 'Email',
                    ],
                ],
                [
                    'GETvar' => 'tx_newsletter_p[c]',
                    'cond' => [
                        'prevValueInList' => 'Email',
                    ],
                ],
                [
                    'GETvar' => 'tx_newsletter_p[n]',
                ],
                [
                    'GETvar' => 'tx_newsletter_p[l]',
                ],
                [
                    'GETvar' => 'tx_newsletter_p[p]',
                ],
            ],
        ],
    ],
    // ...
];