### “E-mailer v1.29” Documentation by “Paweł Kłopotowski”

# “E-mailer”

Created: 2016-03-09
By: Paweł Kłopotowski
Email: webmaster@pklopotowski.pl

Thank you for purchasing my Emailer Program. If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here. Thanks so much!

## Table of Contents

1. About this program
2. Installation
3. How it works
4. How to prepare mailing campaign
5. E-mailer features
6. Requirements
7. SMTP configuration description
8. Q&A section
9. Your own component
10. All possible variables in email layout
11. Subscription widget with double opt-in option

### A) About this program - top

This program is for manage mailing campaigns, newsletters. Easy to use for customers without any complications. Simple menu, many examples of email templates. User friendly view. It also contains predefined sample data for easy understanding how it works and step by step instruction included to the system.

### B) Installation - top

Simplified installation process:

1. Create folder on your hosting server
2. Just copy files to this folder
3. Login using default credentials
   - default login name: demo
   - default password: demo
4. Click button to creste databse structure (automatically process)
5. Go to system configuration section and change login and password according to your needs

### C) How it works - top

It sends emails using any SMTP server or PHP mail() function.

Whole sending process uses ajax, so your browser has to be online during this operation. Progress of sending is showed on the browser screen on the progress belt. Mails are send one by one. Interval of sending emails can be set up in settings section. Check your hosting limits for this issue.

Sending emails can be run as background process also. In this case you can close browser and configure admin notyfication when finished. Also sending progress can be checked on campaign in progress view.

### D) How to prepare mailing campaign - top

Whole process is described step by step on the dashboard view.

1. At first add tags, this will help you find customers and will help you easily prepare an advertising campaign
2. Next add emails to your database system. You can also upload CSV file with emails to your data base
3. Add sender, you can decide from whom your customers will receive an email
4. Add template, you can prepare an unlimited number of templates, with unlimited number of attachments
5. Add new campaign, prepare unlimited campaigns. You can send campaign at any time, stop and resume also
6. To select recipients you have to use filter 'search fiels' over recipients table

### E) E-mailer features - top

List of features included in this mailing system:

- Easy to install, just copy to serwer, login and set up db
- Subscription widget
- Import/Export subscribers from/to CSV file
- Sending mail via standard function mail()
- Sending mail via SMTP server
- Unlimited SMTP connections
- Unlimited numer of attachments
- Unlimited mailing list
- Unlimited recipients
- Unlimited tags for recipients
- Unlimited senders – Set up senders email and description
- Unlimited email templates
- Import predefined 30 usefull email templates
- Easy to add/edit email template – WYSIWYG TinyMCE editor used
- Track emails
- Translation ready / multi language
- Unsubscribe link
- Delete all unsubscribers by one button
- Ajax email sending with progress belt showing current sending process
- Dashboard with basic statistics
- Easy prepare new campaign
- Campaign can be stored for future sending
- List of sent campaigns with sufficiency metter
- Check unsubscribers by a particullar campaign
- Change login/password to the system
- Set up data base
- Set up hourly limit for sending emails
- Enable/Disable email tracking
- Clear data base function
- Clear all recipients function
- Clear all tags function
- Clear all campaigns function
- Clear all templates function
- Clear all attachments function
- Clear all senders function
- Q&A section with most popular usefull issues
- Responsive ready
- One file configuration
- User friendly admin panel view
- Dashboard view
- Import sample data
- Run/Stop campaigns
- Default credentials (login:demo/password:demo)

### F) Minimum requirements - top

- Hosting server with PHP minimum 5.6 with PDO library
- MySQL database
- Online hosting and domain
- Online browser

### G) SMTP configuration description - top

- Connection name
  Field for your own usage. You can describe your connection as you wish.

- SMTP address (required)
  It is your SMTP server address, ex.:smtp.gmail.com.

- Force SMTP usage
  Script uses PHP Mailer library. All docs saying to use isSMTP() method, but smtp.gmail.com won't work with this. So here is possibility to disable it.

- Enable SSL/TLS certificate verification
  In a change from earlier versions, PHP 5.6 verifies certificates on SSL connections. If the SSL config of the server you are connecting to is not correct, you will get an error. The correct fix for this is to replace the invalid, misconfigured or self-signed certificate with a good one. Failing that, you can allow insecure connections disabling this checking.

- Enable SMTP authentication
  Depends on your server. You can disable authorization if your configuration allow that.

- SMTP username
  Username in your SMTP server.

- SMTP password
  Password to your account in SMTP server.

- Reply to mail
  You can force reply to address.

- Reply to name
  Specify name of reply to address.

- Encryption
  Choose TLS/SSL protocol.

- Port
  Choose port on your server, usually it is 465, 587, 25.

- Limit per hour
  Set limit of emails which can be send in one hour.

### H) Q&A section - top

1. Why it is better to have own dedicated server for mailing?

   First of all, no limits. For ordinary hosting, you can send up to 1,000 emails per hour and probably the same amount within one day (depending on the hosting limits range from a few hundred to a few thousand emails a day). On your server, you do not have such restrictions and also have the ability to send emails from your domain. You can also send e-mails as if the server was to be under a different domain (it is in this case set the so-called SPF records and TXT domain - for details ask your hosting provider).

2. What are tags?

   Make it easy to find mailing addresses and preparing an advertising campaign at a specific recipients.

3. How to add the name of the recipient to email template?

   Use phrase {RECIPIENT_NAME} in the content template email or in the title of the template mail. The phrase will be replaced by the name of the recipient e-mail, in case that the information has been added to the recipient's email address.

4. How to add a new translation?

   Copy the file reference english.php, give it a name that describes your language for example mylanguage.php and paste to the same folder. Correct all the texts contained in the new file. Be sure to save the file in UTF-8 w / o BOM. Language file is in the directory 'languages'.

5. How do I add tags to an email?

   First, you need to add a few tags using add tags menu in the email addressess section. Then when you add/edit each email address can be assigned to any tag. All tags will be added below the form to add/edit recipients.

6. How to add the ability to unsubscribe out of receiving messages?

   Use phrase {UNSUBSCRIBE} in the link in the email template content. The phrase will be replaced with a link for the particullar recipient. When he/she will click it, system will save in the database information about the discharge of the campaign. Email address will not be removed from the database.
   Usage:
   <a href='{UNSUBSCRIBE}'>unsubscribe from the newsletter</a>.

7. How to add predefined email templates?

   30 sample templates mailing, click add templates in the usefull extras section

8. How do I add images to e-mails?

   - As an attachment to an email. In this case, the template IMG tag attribute SCR must be set to contentID, means CID, eg:
   <img src='cid:logo.jpg' >
   - As an absolute link to an image in external resources, such as:
   <img src='http://www.domain.ext/logo.jpg' >.

9. How does the tracking of emails?

   For each sent email system can add an image tag IMG, which attribute SRC contains tracking code to display a specific message. Tracking will only work when the mail recipient agrees to show images of the received message.

10. How not to be a spammer?

    - Collect consent to receive messages when creating a mailing list.

    - Use a variety of content for each recipient, use ex. {RECIPIENT_NAME} to differentiate checksums of your mailing.

    - Do not use the keywords like: sex, viagra, porn.

    - Do not use key phrases such as: address from a public database, it is not commercial information in mind, uninterested Sorry, it does not constitute an offer within the meaning if you do not want, click here to unsubscribe, free, special offer, buy it now - if you have to use this such phrases you should consider to put them in the form of graphics.

    - Do not use too many graphics, spam filters examine the ratio of the graphics to text.

    - Mail should not be too heavy.

    - The fewer the better attachments.

    - Do not impersonate another domain.

    - Do not send emails from non-existent email address.

11. How to increase clicks and reads campaign?

    The biggest influence on the content that you send to your customers and the time and the frequency with which you do it. In most cases, the contact should not be more frequent than two times a month. Respect your customers and they will not throw you to the spam.

12. How to choose the addresses for mailing?

    Using tags, type them separated by spaces in the search field above the table of addresses.

13. What are the limitations of this system?

    There is no restrictions, but the bottleneck may be your computer. The program uses AJAX to send e-mails IDs are stored in the browser's memory.

14. Limit messages on the server hosting?

    Depending on the hosting limits range from a few hundred to a few thousand emails a day, check with your service provider.

15. Broken connection when sending campaign?

    You can resume the sending of campaigns, emails will be sent to the other recipients. Each sent email sets a unique marker in the database and the campaign itself will not be re-sent to the same recipient.

### I) Your own component - top

You can add your own component to this mailing system. There is an example component with some description in the code prepared in folder 'components/example_component'. Make a copy of it and add your custom code.

Base component structure:

- view.example_component.list.php - listing data from any source
- view.example_component.add.php - adding data manually
- view.example_component.edit.php - editing data
- controller.php - manage actions
- action.example_component.delete.php - deleting data from database
- action.example_component.insert.php - inserting data to database
- action.example_component.update.php - updating data in database

Posting data rules:

- must be included in every form to avoid CSRF attacks
  `<input type="hidden" name="csrf_token" value="<?php echo $app->getToken();?>">`
- link to html form actions for data modyfying
  index.php?manage=example_component&data=modify&action=update
  - index.php - main file
  - manage=example_component - component to be used
  - data=modify - to avoid renedering html
  - action=update - action to be performed

Receiving data rules:

- must be included in every file to avoid direct access
  `defined('_MAILING') or die('Restricted access');`
- must be included in every file receiving data to avoid CSRF attacks
  `$app->checkToken();`
- all id's should be casted to integer
  `$id = (int)$_POST['id'];`

Prepare menu link to your component:

- production/index.php - you have to add manually in the section 'sidebar menu' link to your new component. It should be like: 'http://localhost/mailing/index.php?manage=example_component&action=list'

### J) All possible variables in email layout - top

There is a possibility to use some variables in email templates. These variables will be changed for some data from the system during sending process.

For email subject:

- {RECIPIENT_NAME} - get recipient name from the system

For HTML version:

- {RECIPIENT_NAME} - get recipient name from the system
- {RECIPIENT_NAME_1} - get first word from recipient name from the system
- {RECIPIENT_NAME_2} - get second word from recipient name from the system
- {RECIPIENT_NAME_3} - get third word from recipient name from the system
- {RECIPIENT_EMAIL} - get recipient email from the system
- {RECIPIENT_DESCRIPTION} - get recipient description from the system
- {UNSUBSCRIBE} - produce unsubscribe link
- {BROWSER_VIEW} - produce email browser view link
- {CAMPAIGN_NAME} - current campaign name
- {SENDER_NAME} - sender name
- {SENDER_EMAIL} - sender email address
- {CURRENT_YEAR} - current year in YYYY format
- {CURRENT_MONTH} - current month in MM format
- {CURRENT_DAY} - current month in DD format
- {F0} - additional recipient field 0
- {F1} - additional recipient field 1
- {F2} - additional recipient field 2
- {F3} - additional recipient field 3

For TXT version:

- {RECIPIENT_NAME} - get recipient name from the system
- {RECIPIENT_NAME_1} - get first word from recipient name from the system
- {RECIPIENT_NAME_2} - get second word from recipient name from the system
- {RECIPIENT_NAME_3} - get third word from recipient name from the system
- {RECIPIENT_EMAIL} - get recipient email from the system
- {RECIPIENT_DESCRIPTION} - get recipient description from the system
- {UNSUBSCRIBE} - produce unsubscribe link
- {CAMPAIGN_NAME} - current campaign name
- {SENDER_NAME} - sender name
- {SENDER_EMAIL} - sender email address
- {CURRENT_YEAR} - current year in YYYY format
- {CURRENT_MONTH} - current month in MM format
- {CURRENT_DAY} - current month in DD format
- {F0} - additional recipient field 0
- {F1} - additional recipient field 1
- {F2} - additional recipient field 2
- {F3} - additional recipient field 3

### K) Subscription widget - top

Your potentially customers can subscribe to this mailing system. There is subscription form generator included.

Widget options:

- Comment about new recipient - adding description to the recipient
- Name - show/hide recipient name field
- After submit subscription widget - choose action to perform after customer make submission
- Add tags - choose tags
- Double opt-in - this means that when the user places their email in the widget, an email will automatically be sent to the user to confirm their action. This way, it will be legitimate and will comply with spam laws
- Email title - confirmation mail title
- Email message - confirmation mail message (supports HTML version), do not forget to use {CONFIRM_LINK} in your confirmation email layout, it will be changed to subscribtion link confirmation for your customer
  example:
  - <a href="{CONFIRM_LINK}">SUBSCRIBE ME</a>
  Possible subscription email variables:
  - {SUBSCRIBER_EMAIL} - subscriber email address
  - {SUBSCRIBER_NAME} - subscriber name
  - {SUBSCRIBER_COMMENT} - your description about subscriber
  - {SUBSCRIBER_TAGS} - used tags
  - {CURRENT_YEAR} - current year in YYYY format
  - {CURRENT_MONTH} - current month in MM format
  - {CURRENT_DAY} - current month in DD format
- Redirect to after confirmation - where to redirect your customer after subscription confirmation process, in other words, redirect customer to this address after clicking confirmation link in the confirmation email
- Notify admin about new subscriber - enable administrator notification when new subscription is added.
  Possible admin email variables:
  - {SUBSCRIBER_EMAIL} - subscriber email address
  - {SUBSCRIBER_NAME} - subscriber name
  - {SUBSCRIBER_COMMENT} - your description about subscriber
  - {SUBSCRIBER_TAGS} - used tags
  - {CURRENT_YEAR} - current year in YYYY format
  - {CURRENT_MONTH} - current month in MM format
  - {CURRENT_DAY} - current month in DD format
- The server to send mail for subscription widget - choose server to send subscriber email

Once again, thank you so much for purchasing this Program. As I said at the beginning, I'd be glad to help you if you have any questions relating to this mailing system. No guarantees, but I'll do my best to assist.

Paweł Kłopotowski

Go To Table of Contents