Direct Mail Tutorial

Direct Mail Tutorial Extension Key: direct_mail_tut Copyright 2000-2003, Marlies Cohen, <mc@mcuniverse.com> This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml The content of this document is related to TYPO3 a GNU/GPL CMS/Framework available from www.typo3.com Table of Contents Direct Mail Tutorial...1 Introduction...2 What does it do?...2 Installing Direct Mail Module...3 Mail User Administration...3 Administration Typo3 Template...4 Direct Mail Module...6 Direct Mail Typo3 Template...8 Editing Direct Mail Module...9 Configuring the Newsletter HTML Template...10 Using Direct Mail - Step by Step Instructions...15 Accessing Direct Mail Plugin...15 Module Configuration...16 Recipient List...17 Recipient List Types...19 Newsletter...22 Selecting an Existing Newsletter...23 Create DirectMail...24 Mass-send...26 Send Direct Mail...28 Creating a Newsletter...30 Compiling the Newsletter...30 Newsletter Categories...33 Direct Mail Tutorial - 1

Introduction What does it do? This tutorial is divided into 3 parts. Move from one page, starting at the top and you will create your own mailing easily. Part One - Step by Step explains how to send newsletters to subscribers. Part Two - Creating a Newsletter explains how to put a newsletter together so that subscribers only get the content they subscribed for. Part Three Setup explains how to install and setup the DirectMail Plugin in Typo3. Direct Mail Tutorial - 2

Installing Direct Mail Module Mail User Administration Installing Direct Mail Plugin There are 2 parts to this plugin: 1. An administration page where the users subscribe, and 2. The Direct Mail Module is the engine that generates the mailing. Newsletters are also stored in subfolders of the module. The newsletters are basically a regular page with content and subsequently; a mailing is created based on the newsletter page. Make sure you have the following extensions installed and active 'Web->Plugin->Direct Mail' 'Address list' 'Direct Mail Subscription' Mail User Administration On the 'Mail user administration' page users can subscribe to the newsletter. A subscription generates an "Address" record in the "Direct Mail module". The subscriber is able to maintain his account by email-based authentication. Creating the Mail User Administration Folder The administration folder is a regular page with page content. 1. Create a new page in the directory tree. 2. Create a new page content like the one in the screen shot below. From Type select 'Insert Plugin' From Plugin select 'DirectMail subscription' 3. Save the new page content Direct Mail Tutorial - 3

Administration Typo3 Template This is how your Mail User Administration Typo3 Template should look. I went to the Direct Mail Example and copied the template from there. 1. This ID is the for the 'Direct Mail Module' Folder you are using. You can create a new one in your website or use the one from the example outside your website. They both will work. 2. The code here needs to be all on one line. I only split it up to make it visible. The template file could also be moved to the fileadmin/media/scripts folder and the link will just have to be changed accordingly here. 3. There is no need to make any changes to the Setup field 4. Make sure that there are checkmarks in the Clear Constants and Setup boxes and none in Rootlevel. Direct Mail Tutorial - 4

5. In Include Static there are 2 items: content (default) and plugin.feadmin.dmailsubscrip... Direct Mail Tutorial - 5

Direct Mail Module In the 'Direct Mail folder' all the subscribers are stored and the newsletters are stored in subfolders. In the "Direct Mail folder" you'll also find a template which determines the design of the newsletters and furthermore there are "Direct Mail records" which represents a 'direct mail campaign' based on a certain newsletter and bound for a certain selection of subscribers. Installing the 'Direct Mail Module' 1. Create a new folder 2. Go to Edit Header and from the Type drop down menu select 'Sysfolder'. Or Copy the 'Direct Mail Module' folder from the Direct Mail Example and paste it after the 'Mail User Administration' folder you have just previously created. If you copied the folder you will not have to make any changes to the folder. If you created a new folder you can follow the information given under 'Module Configuration' and set it up the way you want it or start of with this information in the Tsconfig field and then make changes later in the 'Module Configuration'. ## CONFIGURATION of the direct mail module: mod.web_modules.dmail { from_name = John Spam Doe from_email= john.doe@nothing.test organisation = John Does Testsite replyto_email = replyto_name = plainparams = &type=99 HTMLParams = # UID's of the tt_address records to use for test-sending: test_tt_address_uids = 13,14 # table name of a userdefined table similar to tt_address (same fields) which may be used for distribution also. usertable = enableplain = 1 enablehtml = 1 http_username = http_password = sendoptions=3 categories { 1 = Food 2 = Books 3 = Sport 4 = Religion } } Direct Mail Tutorial - 6

mod.web_dmail.test_dmail_group_uids=1,2 mod.web_modules.dmail.categories.0=food mod.web_modules.dmail.categories.1=books mod.web_modules.dmail.categories.2=sport mod.web_modules.dmail.categories.3=religion mod.web_modules.dmail.categories.4= mod.web_modules.dmail.sendoptions=3 mod.web_modules.dmail.long_link_mode=0 mod.web_modules.dmail.quick_mail_encoding=0 Note Make sure that you have selected Direct Mail from the drop down menu in the 'Contains plugin section. Now save your file. Direct Mail Tutorial - 7

Direct Mail Typo3 Template This is the Typo3 Template that is associated with the Direct Mail Module. Constants and Setup fields are empty. Clear: Constants and Setup have checkmarks in the boxes Rootlevel has no checkmark in the box Include Static has template; NEWSLETTER, plugin.alt.plaintext (99) and cset (default) included (if you include CSet (default) you will have problems with the emails) Direct Mail Tutorial - 8

Editing Direct Mail Module After testing the Direct Mail Module you end up with a whole bunch of sent mail. How do you gain access to those items to delete them? Simple. Select 'List' in the Typo3 column then click on the 'Direct Mail Module' folder and you will see the screen shot below in your workarea. Apart from the normal 'Page' and 'Template' sections there are now Address, Direct Mails and Direct Mail Groups sections. Address Here you see at a glance all the addresses of your subscribers. Direct Mails All the mailing you have sent are listed here. Direct Mail Groups All the Groups you have created are listed here. Direct Mail Tutorial - 9

Configuring the Newsletter HTML Template Now the Newsletter HTML Template has to be included and changed to reflect our customization. Create the Newsletter Page In Kasper's Direct Mail Example he created a hidden folder that contained the Direct Mail Module and the newsletter page. I just placed the newsletter page above the Direct Mail Module in my tree structure. The newsletter page is a page with an 'Insert Plugin' Type as you can see in the screenshot below Then create a Typo3 Template to go with the just created page. Typo3 Template for the Newsletter This is a screenshot of the customized Typo3 Template for the Newsletter Direct Mail Tutorial - 10

Customizing the Plugin To customized the plugin go to Template --> Constants Editor --> Plugin.Feadmin.dmailsubscription (9) and make the changes to suite you. Direct Mail Tutorial - 11

I only customized the following sections: Direct Mail Tutorial - 12

Template File This now points to my newsletter template. The default one is at media/scripts/fe_admin/dmailsubscription.tmpl. Administration Email This is an important part, because if you leave it out you will not be notified when people subscribe to your newsletter. Record PID I have the Direct Mail Plugin in the template associated with the Newsletter Page and not the Direct Mail Module. ID 475 is the ID of the Direct Mail Module in my site structure. Customize Newsletter HTML File The last step is now to make the html template file reflect your categories. The original template file is here: media/scripts/fe_admin/dmailsubscription.tmpl Note I prefer to work with copies in case something goes wrong, so either rename the original or create another copy with a new name. The template file is setup to work just fine, but the categories do not automatically copy themselves into that file. So you will have to manually copy your categories to the file. This is the category code from the original template: <b>select Special Categories:</b><BR> <table> <tr> <td>###gw2b###food###gw2e###</td> <td><input type="checkbox" name="fe[tt_address] [module_sys_dmail_category][0]"></td> </tr> <tr> <td>###gw2b###books###gw2e###</td> <td><input type="checkbox" name="fe[tt_address] [module_sys_dmail_category][1]"></td> </tr> <tr> <td>###gw2b###sport###gw2e###</td> <td><input type="checkbox" name="fe[tt_address] [module_sys_dmail_category][2]"></td> </tr> <tr> <td>###gw2b###religion###gw2e###</td> <td><input type="checkbox" name="fe[tt_address] [module_sys_dmail_category][3]"></td> </tr> </table> To change the 4 original category names, just replace them with your categories. Direct Mail Tutorial - 13

If you have more than 4 categories, just copy one cell from <tr>...</tr> and make the changes. Replace the name of the category and change the number to reflect the number you have in your TypoScript. Direct Mail Tutorial - 14

Using Direct Mail - Step by Step Instructions Accessing Direct Mail Plugin To access the Direct Mail Plugin 1. Click 'Plugins' in the Typo3 column 2. then in the Navigation Column (second colum) click on 'Direct Mail Module'. You will then see the screen below in the workarea to the right (third column). From here you can access direct mail you have created beforehand create a direct mail newsletter link to a webpage with the information you want in your direct mail. Direct Mail Tutorial - 15

Module Configuration Here you Set Default Values for Direct Mails Configure Technichal Options Create Categories These settings can also be changed in the TScript of the 'Direct Mail Module' Sysfolder in Setup. SET DEFAULT VALUES FOR DIRECT MAILS: 'From' email Enter the sender email address. (Required) Example: john.do@nothing.test 'From' name Enter the sender name. (Required) Example: Your Name 'Reply To' email Enter the email address to which replys are sent. If none, the 'From' email is used. (Optional) 'Reply To' name Enter the name of the 'Reply To' email address. If none, the 'From' name is used. (Optional) 'Return Path' Enter the return path email address here. This is the address to which non-deliverable mails will be returned to. If you put in the marker ###XID### it'll be substituted with the unique id of the mail/recipient. Organisation name (Optional) Example: Company Name Default Format options Select the format of the mail content. If in doubt, set it to 'Plain and HTML'. The recipients are normally able to select their preferences anyway. HTML parameters Enter the additional URL parameters used to fetch the HTML content. If in doubt, leave it blank. Plain Text parameters Enter the additional URL parameters used to fetch the plain text content. If in doubt, set it to '&type=99' which is standard. Use: &type99 Long link RDCT url If you enter a http://../ url here it should point to the index.php script of typo3 without any query-string. Then the parameter? RDCT=[md5hash] will be appended and the whole url used as substitute for long urls in plain text mails. This configuration determines how QuickMails are handled and further sets the default setting for DirectMails. Not only links longer than 76 chars but ALL links Option for the RDCT-url feature above. Encoding for quick mails Select the encoding you want to sending of quick-mails. Direct Mail Tutorial - 16

Note: I don't know what these mean. If anybody knows, please contact me so that I can explain it. CONFIGURE TECHNICAL OPTIONS Allow Plain Text emails Set this if you want to allow plain text emails to be fetched. If in doubt, check this option. Place a checkmark in this box Allow HTML emails Set this if you want to allow HTML emails to be fetched. If in doubt, check this option Place a checkmark in this box HTTP username If the mail content is protected by a HTTP authentication, enter the username here. The username and password is used to fetch the mail content. They are NOT sent in the mail! If you don't enter a username and password and the newsletter pages happens to be protected, an error will occur and no mail content is fetched. HTTP password... and enter the password here. List of UID numbers of test-recipients Before sending mails you should test the mail content by sending testmails to one or more test recipients. The available recipients for testing are determined by the list of UID numbers, you enter here. So first, find out the UID-numbers of the recipients you wish to use for testing, then enter them here in a comma-separated list. List of UID numbers of test dmail_groups Alternatively to sending test-mails to individuals, you can choose to send to a whole group. List the group ids available for this action here: AVAILABLE CATEGORIES Category 0 Category 1 Category 2 Category 3 Category 4 Category 5 Category 6 Category 7 Category 8 Category 9 Example: Food Example: Books Example: Sport Example: Religion (You can use categories from 0-30 inclusive. However this interface shows only 10 categories for your convenience.) Recipient List From the drop down menu select 'Recipient List' Direct Mail Tutorial - 17

and you will see the screen below If there are no Mail Groups listed go to chose 'Create new?' Direct Mail Tutorial - 18

Recipient List Types Once you have chosen either to create a new mail group or clicked on the pencil icon see the screen below. next to an existing group you will Depending on the drop down menu you choose under Type: you create different mail groups. By default it opens to 'From Page' Type. From Pages Type The 'From Pages Type' uses address that are found on pages in the website. You select a starting point which in the example is the 'Direct Mail Module' File. The reason I chose this starting point is that all subscription addresses are stored with that file. To see all the addresses you click on Page in the Typo3 column --> then on Direct Mail Module in the Navigation column --> and in the work area you will see page header and page content information and addresses. For a screen shot go to Editing DMM Content. 1. Title Give your group a title that is descriptive 2. Description Fill in the description field 3. Startingpoint Select the starting point by clicking on the ' Browse for records' button and select the file you want as starting point for collecting your address for this group. 4. Recursive I haven't quite figured out yet what this does exactly 5. Tables I haven't quite figured out yet what this does exactly 6. Must Attend Categories If you create lists with subscribers to specific categories you can set that category here. Now all the people on this list will only get the information destined for that particular category. 7. Save the group. Direct Mail Tutorial - 19

Plain List Type The Plain List Type does exactly what it says. It will send only plain text mail, no HTML. In this type you have to add your addresses manually in the Recipients box. 1. Title Give your group a title that is descriptive 2. Description Fill in the description field 3. Recipients The emails have to be entered in a specific way for the list to work. There are 2 choices: [a] email space comma and then press the enter key for a new line [b] CSV [name],[email] - I have not been able to get this to work and can't tell you what the format is. 4. Save the group Static Group Type In the 'Static Group Type' email addresses have to be manually added to the group. 1. Title Give your group a title that is descriptive 2. Description Fill in the description field 3. Recipients Click on the ' Browse for records' button and select the email from the address options that are given. 4. Save the group Direct Mail Tutorial - 20

Direct Mail Tutorial - 21

Newsletter Selecting Newsletter from the drop down menu will change your screen to the view below Now you can select a newsletter that you have created previously. You can select the newsletter by either clicking on the yellow file folder or by clicking on the name of the newsletter. Or create a new newsletter by clicking on 'Click here to create a new page that you can later send as direct mail' Direct Mail Tutorial - 22

Selecting an Existing Newsletter After you have selected an existing newsletter file as the base for your direct mail you will get the screen below. 1. To see how your newsletter looks online in the browser click on ' View Page' 2. To make changes to your newsletter click on ' Edit Page' Hold on a minute and don't press the create button just yet! In the bottom half of the workarea is an other area which needs your attention. 5. When people subscribe to your newsletter their are asked which categoies they are interested in by selecting the check box. The reason behind this is that now you can create newsletters with information for all categories, but you only want to send it to subscribers to 'Books' for example. By selecting the 'Books check box your newsletter subscriber will only see the information you created for the 'Books' section. 6. When you're done click on 'Update category setting'. Now you can create your direct mailing 3. When you are satisfied that everything is ok you click on ' Create new direct mail based on this page'. 4. Now you will see the popup window below. As I was testing I kept on creating new direct mails based on the same newsletter and as you can see the program kept track of my attempts. Direct Mail Tutorial - 23

Create DirectMail This is the screen you see after you have pressed shows the top half of the information. ' Create new direct mail based on this page'. The screen shot below The Subject is the name you have your newsletter in the 'page header'. I haven't really fully customized the information yet as you can see from the screen shot. Click on ' Edit' to customize the information to the current newsletter you are sending. Everything is pretty much self explanatory. Mail Page is the ID of the newsletter you are sending. Parameter, Plain text: &type=99 makes the newsletter is ledgeable in plain text. Parameters, HTML is ok to be empty to work. Below Edit you have again the option to have another look at your newsletter. Clicking the yellow folder or on the file name will take you back to your previous screen. At the bottom of the work area is now the 'OPTIONS:' Menu. Your next step is now to compile your Direct Mail and you do that by clicking on 'Fetch and compile maildata (read url) from the drop down menu and you will see the screen below Now you press the 'Read URL' button and wait. Don't do anything else on the computer or it will not work. Multitasking is out of the question or you will have to start to read the URL again. And yes, it does take some time (2-3minutes), so get up and do something else. Direct Mail Tutorial - 24

Once the URL is read you will back to the screen at the top of this page. Note Once the newsletter is read it stays in the memory until it is sent, even if it is the next day and you have turned off Typo3 and your computer in the meantime. Direct Mail Tutorial - 25

Mass-send After the URL is read, you scroll back down to OPTIONS and there will be 2 more added Send a testmail and Mass-send mail. Select 'Mass-send mail' Your screen will change to the one below This screen gives you 2 choices for sending the mail. 1. 'Select a mail group' to send the mail to 2. 'Send Mail - List of Emails' Select a Mail Group 1. From the drop down menu select the Mail Group you want to use for this mailing 2. Click on the 'Send to all subscribers in mail group' button. 3. Now you will see the screen below Direct Mail Tutorial - 26

4. Click on the Back button and follow the instructions on the next page 'Send Direct Mail' Send Mail - List of Emails If you have list of email you want to use for your mailing select this Option. So that there is no overlap or unwanted emails being sent I created a Recipient list of the Static Group Type, but left the Recipients box empty. To use this option 1. prepare you mailing as usual, 2. after the URL has been read 3. scroll down to the second option 'Send Mail - List of Emails' and place the emails in the box and 4. hit send button. With this option the mails are sent immediately, there is no need to start the mailer. engine. Your screen will now look like the one below. It tells you that the mail was sent and who it was sent to. Direct Mail Tutorial - 27

Send Direct Mail Now you select from the drop down menu 'Mailer engine status'. Your screen will change to the one below 1. A newsletter is scheduled to be sent. 2. Start your Mailer engine by clicking on the text 'Invoke Mailer Engine' Now things move quite quickly. Direct Mail Tutorial - 28

1. The status of the Mailer engine is indicated and a log given of what transpired. - The time it was started - The name of the newsletter that was sent - How many copies were sent and which address used (tt_address) - How long it took to send the mail 2. Under the Mail Engine Status you now can see that your newsletter has been delivered and 2 copies sent. Direct Mail Tutorial - 29

Creating a Newsletter Compiling the Newsletter I am using the Newsletter #1 that is included in the 'Direct Mail Example' as a reference to explain how to format the newsletters you create so that subscribers only see content for which they subscribed. This is an overview of the newsletter in 'List Mode' The sample Newsletter has 9 content sections and is setup to use the 'Normal Column' and the 'Border Column'. See screen shot below. 1st Content Section This is the greeting and intro section and uses 'Data Fields' to personalize the mailing. You can find the list for the 'Data Fields' under --> Plugins --> Direct Mail Module --> Instructions from the drop down menu. Direct Mail Tutorial - 30

Data Fields in Direct Mails You can insert personalized data in the mails by inserting these markers: ###USER_uid### (the unique id of the recipient) ###USER_name### (full name) ###USER_firstname### (first name calculated) ###USER_title### ###USER_email### ###USER_phone### ###USER_www### ###USER_address### ###USER_company### ###USER_city### ###USER_zip### ###USER_country### ###USER_fax### ###SYS_TABLE_NAME### ###SYS_MAIL_ID### ###SYS_AUTHCODE### (In addition ###USER_NAME### and ###USER_FIRSTNAME### will insert uppercase versions of the equalents) 2nd Content Section This section is placed into the 'Border Column' and links to the Sitemap. In the example it is configured like this in header section of the content: Type: 'Menu/Sitemap' is selected. Menu Type: 'Section index (pagecontent w/index checked' is selected. 3rd Content Section This section is also placed into the 'Border Column' uses the 'News Plugin'. In the example it is configured like this in the header section of the content: Type: Insert Plugin Header: [News Splash] Plugin: News Code: LATESTS Startingpoint: News Recursive: 2 levels 4th-7th Content Sections These 4 sections correspond to the 4 categories in the example: Books, Food, Religion and Sport. Create a separate content for each category, don't put them all together into one content section. 8th Content Section This section links to other pages. In the example it is configured like this in the header section of the content: Type: Insert Records Name: [insert record..] Items: Links, Tables, Filelinks, Email form Layout: Normal 9th Content Section The last section links to the Search Page for your site. In the example it is configured like this in the header section of the content: Type: Search Direct Mail Tutorial - 31

Header: Search for your favorite Stuff Send to Page: Search Now that you have created your newsletter you need to match the sections to the categories of your subscribers. Go the the next page. Direct Mail Tutorial - 32

Newsletter Categories You can link the newletter to the categories now or when you are ready to mail the newsletter. Just don't forget to do it. I placed a reminder in the tutorial under Select Newsletter. Clicking on Plugins --> Direct Mail Module or the name of the Newsletter you just created will open the Newsletter Direct Mail Edit Page. Here you see all the newsletter(s) that you have created. You can view them from here, edit them, create your mailing based on them and select the categories that go with each content section. Leaving all the check boxes blank will automatically include that section for all subscribers. Selecting checkboxes to match subscribers category choices will send that page content only to subscribers. At the bottom of the page is an update button to save your settings. When you set your categories as you create your newsletter you won't have to worry remembering to set them at the time of your mailing. This way if you create your newsletters in advance or in bits and pieces, by automatically setting the categories you are always up-to-date. Direct Mail Tutorial - 33

Direct Mail Tutorial - 34