Looking for the latest version? Download pythonbulkmailer.zip (81.3 kB)
Home
Name Modified Size Downloads / Week Status
Totals: 3 Items   191.9 kB 15
pythonbulkmailer.tar.gz 2011-08-13 77.1 kB 1212 weekly downloads
pythonbulkmailer.zip 2011-08-13 81.3 kB 22 weekly downloads
readme.txt 2011-08-12 33.4 kB 11 weekly downloads
Python Bulk Mailer V0.2 August 2011 (c) Leslie Jones FEATURES: * FREE * CROSS PLATFORM (ANYWHERE PYTHON RUNS, THIS RUNS) * EASY TO SET UP & USE * NO DATABASE REQUIRED - WORKS WITH .csv FILES * SIMPLE TEXT FILE CONFIGURATION * MULTI-MODE (direct to MX, via smarthost/relay or use EMAIL accounts) * SENDS PLAIN/HTML EMAILS WITH ATTACHMENTS * SUPPORTS PER MAIL CUSTOMISATION OF SUBJECT, NAME AND MULTIPLE BODY ELEMENTS * LOGS DELIVERY AND FAILURE TO .csv FILES * TRACKS OPENING/VISITS VIA INCLUDED PHP HANDLER * PROVIDES UNSUBSCRIBE/SPAM REPORTING VIA INCLUDED PHP HANDLER LICENCE #Copyright 2011 Leslie Jones All rights reserved. # #Redistribution and use in source and binary forms, with or without modification, are #permitted provided that the following conditions are met: # # 1. Redistributions of source code must retain the above copyright notice, this list of # conditions and the following disclaimer. # 2. Redistributions in binary form must reproduce the above copyright notice, this list # of conditions and the following disclaimer in the documentation and/or other materials # provided with the distribution. # 3. You are not permitted to sell this software or use it in a commercial product # Without the prior written agreement of the author. #THIS SOFTWARE IS PROVIDED BY Leslie Jones ''AS IS'' AND ANY EXPRESS OR IMPLIED #WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND #FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Leslie Jones OR #CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR #CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR #SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON #ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING #NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF #ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. #The views and conclusions contained in the software and documentation are those of the #authors and should not be interpreted as representing official policies, either expressed #or implied, of Leslie Jones. INTRODUCTION ============ PBM is a console/cli based FREE bulk mail sender written in Python. It has been written to offer flexible mailing options and should find uses with those who have to send LEGITIMATE bulk mail. It does not use any databases and runs off simple text & CSV files. Whilst this is not the fastest way to perform, it offers simplicity for newcomers to bulk mailing. The program is linear, that is each email address is tried and processed in turn - there is no forking of additional processes. It is possible to to run multiple instances of the program with different 'job' names and email lists. The program allows you to send text and HTML emails with or without attachments. These can be delivered direct to MX, via a specific smart host/relay or by using a list of hosts and accounts (such as AOL/GMAIL etc). It allows tracking and individual mail customisation via the concept of 'placeholders'. Additionally it is supplied with a simple PHP web handler that tracks opening/link following and provides a mechanism to record unsubsription requests and spam complaints. The program logs to plain text .csv files for analysing your results. The program should be cross platform and run anywhere that Python is available. It was written with Python version 2.6.5 on a Linux platform and has not been extensively tested with Windows. However I tried it with a fresh install of Python 2.7.2 on a Windows XP virtual machine and after installing the one extra DNS library it uses it worked. However, it *is* fussy as to the order of the options on Windows - particularly the abuse address. THIS WORKED FLAWLESSLEY: C:\Documents and Settings\user1\My Documents\myscripts>bulkmailerRC.py -B text.file -C html.file -j test -e mail.lst -l -x abuse@mydomain.null -E host.domain.null -S "you rock" -F from@address.local -L "http://handler.null/index.php". The program makes use of fairly standard libraries that are usually available without sweating blood. There is one exception to this in the shape of dns.resolver which is available from: http://www.dnspython.org/ The documentation at this site covers installing it. The install instructions for this on either Linux or Windows boxes is pretty much the same. Download, unzip/unpack to a sensible directory. CD into that directory and then type/run: python setup.py install This program has not been designed to send 'spam' and I urge you not to use it for that purpose. It has been designed for legitimate, small scale bulk mailing. I am sure there are much better mailers out there for high speed spammers - such as 'dark mailer' and the like, and I'm hoping this program is used responsibly. This is my first program in Python and the coding style and logic may leave seasoned Python coders crying blood. However, I wrote it to do a job which it performs well and without obvious issues. I would like to thank the excellent website Security Tube (http://www.securitytube.net/) for inspiring me to learn Python after years of working with Perl. The guys and gals have been really supportive and encouraging and I urge those interested in security and coding to check it out. If you find this program useful I would urge you to make a donation to them using the 'donate' button at the site. PROGRAM OPTIONS =============== The options for running the program are given below, examples are given towards the end of this document. -j --jobname A name for this specific job (no spaces or metacharacters) This allows you to run multiple instances of this program under different job names, with different lists of recipients. REQUIRED ==================================================================== One of these options must be selected. -d --dryrun Don't actually send mail, just do a dry run -l --live Live run -t --test Send a single test message to recipient ==================================================================== -r --reset Reset the campaign (default is to resume from last mailed address) (optional) -e --emaillist A CSV list of recipients with optional fields [see readme for more info] REQUIRED -a --accounts A CSV list of email accounts and credentials to use [see readme for more info] (optional) (this option can be used instead of direct to MX or -H below) -v --verbose Turn on verbose output for debugging (optional) -H --host host to send to (optional - if not specified will try direct to all mx) -P --port host port to connect to (optional but required if -h specified) -U --hostuser host username (optional) -W --hostpass host password (optional) -x --abuse A contact email address for ABUSE complaints (REQUIRED) -E --helo ehlo/helo name to use REQUIRED -F --sender sender email address to use REQUIRED -G --sendername sender name (appears before email address in client TO: NAME <address> (optional) -R --recipient recipient email address to use REQUIRED FOR -t --test ONLY otherwise ignored -Q --recipientname recipient name (appears before email address in client FROM: NAME <address> (optional) -q --recipientf2 use field 2 in CSV file for recipients name (optional) -T --tls use TLS (optional) -s --f1sub use the contents of field one in the email list csv file as the subject if possible (optional) -S --subject email subject REQUIRED - this subject will be used if -s/--f1sub is NOT specified or field 1 in the CSV is empty -A --attach file location of attachment (optional) -B --text file location of text body REQUIRED -C --html file location of html body (OPTIONAL BUT SUGGESTED) ERROR SWITCHES -X --conerr Treat connection errors as customer error - not 4xx temporary deferral -Z --greyerr Treat greylisting as customer error - not 4xx temporary deferral TRACKING OPENING & DELIVERY -L --trackhandler The full URL to your web script that handles tracking. (optional) OPERATING MODES =============== The script has a number of operating modes: test Provided to make basic tests so delivery/headers/spam/layout can be tested prior to a live run dry run Provided to go through the motions without actually connecting to an MTA or remote host live run Normal run mode where mail is delivered In addition these modes operating in specific operational modes, these are: direct to mx Mail delivery is attempted directly to the MX for the recipient domain. Do *not* use this mode if you do not have dedicated IP's properly set up with DNS PTR/SPF records or are using a dynamic IP address. smart host Mail is sent to a specified host (optional port/username/password/tls options) for onward delivery. accounts list A list of smart hosts/accounts is provided (such as gmail/aol etc) and the program will rotate them in a round robin fashion CONTROLLING THE MODE: ===================== To control what mode of the mailer we use a few options and some common sense. DIRECT TO MX: If we don't supply an -H (--host) OR an -a (--accounts) option the mailer runs in direct to MX mode. SMART HOST/RELAY: To use a smart host or a relay we make use of the -H (--host), -P (--port), -U (--hostuser), -W (--hostpass) and -T options. ACCOUNTS LIST: To use a list of accounts, we specify the -a (--accounts) option with the path to a csv list of accounts. The account list MUST NOT contain a header row (unlike the email list) and the fields required are: F1: host name or ip address F2: port to connect to F3: TLS on or off (0 = off, 1=on) F4: Username F5: Password If your host does not require a username or password leave them blank eg "", but make sure the fields exist in the csv MAIL TYPES ========== The script will send either text only or text AND html mails depending on the options provided. It also allows attachments. FLAT FILE SYSTEM - NO DATABASE NEEDED ===================================== To keep this mailer simple it uses simple flat files rather than a database. Naturally this has a performance impact, but provides the simplest configuration and use. The body of the email is built from a single text file that can have a degree of customisation using 'placeholders'. This will generate a plain text email and must always be supplied to satisfy all mail clients. HTML emails are generated by supplying an additional HTML file. This can also be customised using placeholders. The main 'email list' should be a CSV file with a header column (pay attention to this as some lists DON'T have a header line). It should be 11 columns long. The first column should contain the recipient email address. Columns 2-11 are used with the placeholders mentioned above and allow you to customise each message on a per recipient basis, based upon your csv file. Some of the fields can be used with options to alter the message such as: -s --f1sub -q --recipientf2 The first option says 'if the csv has a value in field 1, use it for the subject - otherwise use the default subject' The second says 'if the csv has a value in field 2, use it for TO NAME of the recipient, otherwise just use the to email address' It's probably easier to clarify this by showing the different 'to' headers in each case: To: some@emailaddress.com To: Bill Bloggs <some@emailaddress.com> USING PLACEHOLDERS TO CUSTOMISE MESSAGES ======================================== Both the TEXT and HTML files can contain placeholders that are replaced with values from the csv file on a per recipient basis. These take the form ${field to use}|{alternative if field empty}$. It is probably easier to explain it with an example: ...........................text file.................................... Dear ${1}|{valued customer}$ I am writing to you because you live in ${2}|{an area}$ which is currently scheduled as part of the ${3}|{county}$ free cheese project. If you would be interested in taking part in trials, please visit http://mywebsite.null/somehandler.php?ct=${4}|{0}$ Warm regards UK Bovine Supplies ........................................................................ Earlier we mentioned the options: -s --f1sub -q --recipientf2 These don't stop you using fields 1 & 2 in placeholders, but naturally their content needs to make sense in the context of a subject and name. TRACKING, VIEWING ONLINE AND UNSUBSCRIBING ========================================== Tracking email opening is typically done with a web based script that looks for a client to download a tracking image - usually a single transparent pixel. Clients that don't download images (which tends to be the norm now) won't trigger such mechanisms, so a 'view online' link is usually included in each email that will trigger the same mechanism. The mailer is provided with a simple PHP script that provides these functions, along with the ability to request unsubscription and report the message as spam. Again this uses flat files instead of a database. See the readme for the php handler if you wish to use it, it is simple to set up and use. All you need to do to make use of this is to put either (or both) of the special placeholders shown below in your HTML message: For the tracking link just add: ${tracklink}$ For the view online option the context depends on if the mail is text or HTML. In an HTML mail you need to wrap the placeholder in a link like this: <a href="${viewonline}$">View this message online</a> In a text only mail <a links make no sense, so instead we would use something like: You can view this message online at the following link: ${viewonline}$ The PHP handler supplied is able to deal with requests to unsubscribe and even offers the chance for recipients to report messages as spam. To make use of this all you need to do is include the ${unsubscribe}$ placeholder much like the viewonline placeholder above: In an HTML mail you need to wrap the placeholder in a link like this: <a href="${unsubscribe}$">UNSUBSCRIBE</a> In a text only mail we would use something like: You can unsubscribe from future mailings by following this link: ${unsubscribe}$ To make use of the PHP handler, you need to tell the program where it is on the internet with the -L (--trackhandler) option: -L 'http://example.null/handler/handler.php' The tracklink placholer provides a single transparent pixel which fires if 'view images' is on in the mail client, whereas the viewonline placeholder provides a full 'click' link to view the mail online. Note the tracklink only makes sense in HTML mails as it is an HTML image element, so don't include it in the text version. You don't have to use my simple PHP handler and can either alter/extend it to work as you wish or provide your own handlers and make use of fields & placeholders to trigger them, you are not limited to my simple implementation. Full examples are given at the foot of the page. For more details on the PHP handler, see its readme file. LOGGING ======= Half of the job of bulk emailing is creating logs and reports and This program will do some of that work for you. The program creates csv logs for every attempted email along with separate logs for successful deliveries and errors. These files are created using the jobname are created in the directory the program is run in (so make sure it has write permissions). You can use these files to create reports by analysing them in suitable software. Please note that there are also a couple of other files created that should be left alone. These are the deferred log and position file. These keep track of what has been done if you should stop the program, and allow it to restart from where you left off. If a job is called 'test123' you'll probably find the following files created: test123_attempts.log test123_delivered.log test123_error.log but please do not interfere with test123_defer.log test123_main.pos SPEED ===== This is a linear program that is quite happy to chug along and send your messages either direct to MX or via a number of email accounts but it's probably not going to win any world records for speed. If performance is important to you you'll probably find the program will give the best results if you split your email lists into different chunks and run multiple copies of this script with different job names on each. You'll also find that delivering directly into your own local MTA as a smart host, and allowing that to do the heavy lifting of the actual delivery, will give the most optimal results. DEFERRALS ========= The mailer handles temporary failures (SMTP 4xx codes) such as greylisting and builds its own deferral retry queue. This tends to come into use in direct to MX/account list mode. In relay/smarthost mode it is unlikey the specified host will reject your mail - but on occasions it may happen, and it is handled by the program as gracefully as possible. BOUNCE MESSAGE PROCESSING ========================= In direct to MX mode this mailer is able to read and make sense of so called 'permanent' SMTP errors (those starting with 5xx eg: 550 no such user). This will immediately be logged as an error and won't be retried. However, if you are sending messages via a relay or smart host it will probably just accept the message into its queue and then bounce it later when it itself gets a 550. This will result in a bounce message coming back your way, so make sure you have something in place to handle these. I am hoping to release an additional tool to complement this mailer which will process a POP3 mailbox for bounce messages. TESTING ======= The bulk mailer has a simple optiont to allow a single test message to be sent (-t --test). This will send a full message (but will not attempt to parse/replace placeholders) to the specified recipient. Some examples of how to use it are shown below: Simple test using direct to MX, text based only (text is in file 'text.file' ./bulkmailerRC.py -t -B text.file -E helo.mydomain.com -S "This is a test" --sender "<my_account_name>@aol.com" -R <recipient>@gwhereever.com -x abuse@yourdomain.null Simple test using direct to MX, text & html (text is in file 'text.file', html in html.file) ./bulkmailerRC.py -t -B text.file -C html.file -E helo.mydomain.com -S "This is a test" --sender "<my_account_name>@aol.com" -R <recipient>@gwhereever.com -x abuse@yourdomain.null Simple test using direct to MX, text & html with an attachement (text is in file 'text.file', html in html.file, attachment is 'attach.zip') ./bulkmailerRC.py -t -B text.file -C html.file -A attach.zip -E helo.mydomain.com -S "This is a test" --sender "<my_account_name>@aol.com" -R <recipient>@gwhereever.com -x abuse@yourdomain.null Simple test using a smart host/mail relay here an aol account with a host of 'smtp.aol.null', a username of 'bogus.mailer@aol.null' and a password of 'secret' ./bulkmailerRC.py -t -B text.file -E helo.mydomain.com -S "This is a test" -R <recipient>@gwhereever.com -C html.file --sender "bogus.mailer@aol.null" -H smtp.aol.null -U bogus.mailer@aol.null -W secret -x abuse@yourdomain.null Note, in the real world you'll probably need to specify a different port AND use TLS (options -P and -T).... ./bulkmailerRC.py -t -B text.file -E helo.mydomain.com -S "This is a test" -R <recipient>@gwhereever.com -C html.file --sender "bogus.mailer@aol.null" -H smtp.aol.null -P 587 -T -U bogus.mailer@aol.null -W secret -x abuse@yourdomain.null OTHER OPTIONS WITH TEST ----------------------- Some options, such as a list of email accounts to use, don't make sense with a one-shot test. If you specify an option that does not make sense to the test option it will usually be ignored. Other options will work such as: -Q --recipientname -G --sendername EG: ./bulkmailerRC.py -t -B text.file -E helo.mydomain.com -S "This is a test" -Q "Fanny Hole" -R <recipient>@gwhereever.com -C html.file -G "Austin Cambridge" -F "bogus.mailer@aol.null" -H smtp.aol.null -P 587 -T -U bogus.mailer@aol.null -W secret -x abuse@yourdomain.null REAL RUNNING EXAMPLES: ===================== Here are some real running examples complete with file contents: ..................... mailinglist.csv .................................. "email addressl1","field 1","field 2","field 3","field 4","field 5","field 6","field 7","field 8","field 9","field 10" "support@somewhere.null","Hey support, it's newsletter time","Support Team","Jon Doe","London","","","","","","" "support@somewhereelse.null","Hey Team, it's good news time","The Team","Jane Bland","Birmingham","","","","","","" "support@somewhereelse.null","","","","","","","","","","" ........................................................................ ..................... accountlist.csv .................................. "somehost.null","25","0","","" "1.2.3.4","2500","0","user@mailhost.null","secret" "smtp.google.com","587","1","username@gmail.null","password" "smtp.aol.com","587","1","user@aol.null","secret" ........................................................................ ...........................text file.................................... VIEW THIS MESSAGE ONLINE: ${viewonline}$ Dear ${3}|{valued customer}$ I am writing to you because you live in ${5}|{an area}$ which is currently scheduled as part of the ${5}|{county}$ free cheese project. If you would be interested in taking part in trials, please visit http://mywebsite.null/somehandler.php?ct=${4}|{0}$ Warm regards UK Bovine Supplies If you would like to unsubscribe from our mailings please visit: ${unsubscribe}$ ........................................................................ ...........................html file.................................... <html> <head></head> <body> <h1>HTML EMAIL TEST</h1> <a href="${viewonline}$">View this message online</a> <p>Hi ${3}|{valued customer}$!<br> I am writing to you because you live in ${5}|{an area}$ which is currently scheduled as part of the ${5}|{county}$ free cheese project.<br/> If you would be interested in taking part in trials, <a href="http://mywebsite.null/campaign">visit us online</a><br/> Warm regards UK Bovine Supplies <br/> If you would like to unsubscribe from our mailings please click: <a href="${unsubscribe}$">CLICK HERE</a> </p> <p>${tracklink}$</p> </body> </html> ........................................................................ SENDING EXAMPLES USING THE FILES ABOVE: ======================================= Direct to MX example: ./bulkmailerRC.py -B text.file -C html.file -j 'jobname01' -e mailinglist.csv -l -E 'helo.mydomain.null' -s -S 'This is the default subject' -F 'sender@ourdomain.null' -L 'http://ourdomain/handler/index.php' -x abuse@ourdomain.null Via a smarthost/relay ./bulkmailerRC.py -B text.file -C html.file -j 'jobname01' -e mailinglist.csv -l -E 'helo.mydomain.null' -s -S 'This is the default subject' -F 'sender@ourdomain.null' -L 'http://ourdomain/handler/index.php' -x abuse@ourdomain.null -H host.domain.null -P 25 -U bogus.mailer@domain.null -W secret Via a smarthost/relay WITH TLS ./bulkmailerRC.py -B text.file -C html.file -j 'jobname01' -e mailinglist.csv -l -E 'helo.mydomain.null' -s -S 'This is the default subject' -F 'sender@ourdomain.null' -L 'http://ourdomain/handler/index.php' -x abuse@ourdomain.null -H host.domain.null -P 25 -U bogus.mailer@domain.null -W secret -T Using an accounts list ./bulkmailerRC.py -B text.file -C html.file -j 'jobname01' -e mailinglist.csv -l -E 'helo.mydomain.null' -s -S 'This is the default subject' -F 'sender@ourdomain.null' -L 'http://ourdomain/handler/index.php' -x abuse@ourdomain.null -a accounts.csv If you have used a jobname the program will usually detect this based upon files in the local directory and offer a chance to resume. This may be necessary if the mailer is interupted for some reason. However you can wipe and reset a job name by adding the -r option. DEBUG/TROUBLESHOOTING/TWEAKS ============================ the -d --debug option will give quite alot of verbose output, including details of the SMTP dialogue. This is useful for debugging. There are some other tweaks that can be made to delivery and looking through the code will reveal some of them these include modifying the mailer name, anti-spam keying header and variables such as 'maxtimeout, maxdeferretries and deferwaitsecs. As it stands no changes need to be made to the program in normal use. BUGS, PROBLEMS, FEATURE REQUESTS AND SUPPORT. ============================================= Every developer wishes they could write bug free code that will handle all errors gracefully - even the team at Microsoft :-) In the real world this does not happen and inevitably there may be the odd (or major) bug in this program. Please feel free to tell me about them or to request features or support. I don't guarantee this software in any way, I don't guarantee that bugs will be fixed, features added or support offered. Use it at your own risk and use of the software is subject to the following licence: Leslie Jones python.mailer [AT] blackmarketeer.co.uk NOTES/UPDATES - DKIM/DOMAIN KEYS ================================ This program does NOT implement DKIM/DOMAIN KEYS. Hoewver, you can *may* be able to implement this on your smart host/relay. At the time of writing this, I've not looked into it in any depth but it is on the 'todo' list. PHP HANDLER README (also in the index.php script) ################################################################################################################################################### # # Simple email campaign responder/handler that uses flat files rather than a database. # # It provides a few simple functions in a single script for basic bulk mail/newsletter # response/online handling. It is designed to complement our simple linear Python bulk # mailer script but you are free to modify it to your own needs. # # * TRACKS OPENING TO FLAT CSV LOG FILE GENERATING A SINGLE TRANSPARENT PIXEL # * BASIC OVERLOOKING PROTECTION USING SIMPLE HASHED EMAIL IN QUERYSTRING # * OFFERS AN UNSUBSCRIBE FACILITY AND LOGS REQUESTS TO CSV LOG FILE # * OFFERS A 'REPORT AS SPAM' FORM AND LOGS COMPLAINTS TO A CSV FILE # * REDIRECTS TO ONLINE VERSION OF HTML EMAIL # * SIMPLE CUSTOMISATION (via global variables and plain English PHP) # * BASIC SECURITY AGAINST DICTIONARY PHISING OF EMAILS + REPLAY/CSRF TYPE HACKS # # To accomplish the various tasks the script operates in a number of different modes depending # on if it gets certain querystrings or form data. These are: # # QUERYSTRINGS THIS SCRIPT HANDLES/RESPONDS TO # ct EG: ct=MzuwL2WyM0OirJ5jrUchMKulM3WlMF5unUy5Pt%3D%3D # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ # This is simply the email address put through a simple Caesar type cipher and mung. # It is not meant to be secure as such, just to stop casual overlooking and tampering. # it is generated by putting the email address through a simple ROT13 function, the result is # then BASE64 encoded and finally this is also put through ROT13. This script reverses the process # to recover the original email address and this is then used ONLY in the logging of OPENING. # It is important to note that this address is NOT used in unsubscribe requests or spam reports. # These force manual input and the reason(s) why will be mentioned in a moment. # # Every time the script is called with the CT querystring present, the 'hit' will be recorded in the log # PROVIDED that the email address within is actually in our mailing list. This approach is taken so we # log all activity from a given recipient, and so that it can be used in emails in 'click here' links # as well as image pixel tracking which depend on the client downloading images. Whilst this may lead to # some duplication in the tracking log, on balance it will show highly active email addresses in some detail. # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ # rq EG rq=us # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ # This querystring is simply the REQUESTED action. It can force four actions to occur depending on # its value *OR* if it is present. # # First of all, if it is missing the script will log any email address in querystring ct as a hit, before # redirecting to a single 1 point transparent pixel. This is typically used in emails to log opening of an # html mail (subject to the mail client downloading images - which is NOT usually the case but CT can still # give some leverage on this) # # Next it can accept the value 'us' (or unsubscribe) and it will then force an unsubsribe form to display. # This subsequently links to a 'report spam' form if required (this can be called/linked directly). # The recipient is required to put their email address into a simple form to unsubsribe and this manual step # is designed so addresses are not unsubscribed by automation/content scanners blindly following links. It also # allows for additional addresses to be unsubsribed. All addresses are checked in the mailing list to make sure # they exists and if present the address is written to a separate 'unsubscribe' log. It is not removed from the list # and left for manual processing or for use with a script that deals with unsubsription requests and bounces and general # mailing list hygiene. Supplying email addresses not in the list does *not* alert the user - it just reports success every time. # This is to stop potential dictionary phishing of email addresses in the list. It's a bit of a compromise, but list security # is deemed more important than a user who wants to unsubscribe not being able to key in their correct email address. # # It can also accept the value 'rs' (or report spam) and jump directly to a suitable form. Spam reports are logged to a # separate file. # # Finally it can accept the value 'rd' (or redirect) and if it sees this will issue a redirect to a url stored in the global # variable: $Glob_Array["redirecturl"] For example, if you wanted to redirect users to 'http://wibblywobblywonga.com/mailout' you # would set your global variable: $Glob_Array["redirecturl"]="http://wibblywobblywonga.com/mailout" and call the script: # http://urltoyourscript/index.php?rq=rd # OR WITH A ct VALUE TOO: # http://urltoyourscript/index.php?ct=MzuwL2WyM0OirJ5jrUchMKulM3WlMF5unUy5Pt==&rq=rd # # Calling the script with bad params or nonsensical params will give a 404 type custom error. # # SET UP # Deploying the script is simple. Create a directory/folder on the server for storing the log files ABOVE your public/htdocs # directory to stop casual browsing from the internet. # Make sure the directory is writeable by your user account. On Windows based servers it probably will be, but *nix systems # may need chmod of some description. Be careful with the use of chmod 777 on shared servers as others can potentially read/write your files. # For the script to work properly you need to upload a copy of your email list in CSV format to this private directory and reference its # location in the global variable: $Glob_Array["emailfile"]. I suggest putting it in your private directory. # PLEASE NOTE THIS CSV FILE MUST BE IN THE FORMAT "emailaddress@whatever","field","field".... etc with the EMAIL address as # the FIRST item. # # GLOBAL VARIABLES # Set up the global variables to match the path to your private directory, and other preferences - there are only six of them: # $Glob_Array["salt"]="somerandomsalt" - this is used in the creation of simple security 'nonces' # $Glob_Array["redirecturl"]="viewonline.html" - redirect URL of a 'view on line' version of email or other web page # $Glob_Array["emailfile"]="/usr/www/yourdirectory/private/email.lst" - location of a copy of your email list # log files: The next and final three are just the locations of your log files for storing the hits, unsubs and spam reports: # $Glob_Array["unsubfile"]="/usr/www/yourdirectory/private/unsubscribe.lst"; # $Glob_Array["reportspam"]="/usr/www/yourdirectory/private/eportspam.lst"; # $Glob_Array["hitslog"]="/usr/www/yourdirectory/private/hits.log"; # # With that, you are set. Just upload the script and its dependent files to your server and test that it works before using it in a mailing. # The forms should work when called: # http://yourlocation/index.php?ct=M3WzM0OuLzc1pzIlYzSbrKxX=&rq=us # http://yourlocation/index.php?ct=M3WzM0OuLzc1pzIlYzSbrKxX=&rq=rs # http://yourlocation/index.php?ct=M3WzM0OuLzc1pzIlYzSbrKxX=&rq=rd # http://yourlocation/index.php?rq=us # http://yourlocation/index.php?rq=rs # http://yourlocation/index.php?rq=rd # and also check without any args: # http://yourlocation/index.php # # The dependent files are: # simple_class.php # style.css # pixel.gif # error.gif # Also make sure any 'show on line' type redirect link exists. #
Source: readme.txt, updated 2011-08-12