Configuration & set-up
In the package
- admin: Contains the files that you (the administrator) will use to operate the application.
- api: sample files with examples and documentation on using the various apis.
- assets: this is where your newsletters images (and other files) are stored. The html editor has a file manager that enables you to upload and insert assets (images) in the email body.
- attachments: this is the folder where your attachments are placed. The upload utility places the files you upload as attachments automatically in this folder.
- data_files: contains csv, txt files for importing subscribers or saving exported files.
- subscriber: contains the public pages that your subscribers use.
- inc: contains the files with the necessary functions for the operation of nuevoMailer.
- install: contains the files to create (or upgrade) your tables when installing. You should remove this folder after you have completed your installation.
- The .htaccess file is optional but good to have. Its only purpose is to disallow directory browsing and indexing of your files and folders (Apache only).
- The most basic entities in nuevoMailer are the subscriber and the newsletter.
All other entities and activities are based on these two.
- A subscriber is someone from whom you have at least an email address.
- A newsletter is the content that you send.
- A mailing list is a way of grouping your subscribers.
- A campaign is the activity of sending a newsletter to subscribers.
- Any newsletter can be send to any mailing list (or a combination of lists or to all subscribers).
- Terms such as opt-in, sign-in, sign-up are equivalent. They mean that a subscriber registers to receive your newsletters.
- Terms such as newsletter and email are used interchangeably. This is because a newsletter is actually delivered via email.
- E-newsletter is an electronic newsletter: a newsletter that is delivered electronically. In the context of email marketing and throughout this guide, for simplicity we use just newsletter.
- Email marketing is marketing done via emails. It is another channel of electronic marketing.
Reading this page means that you have successfully installed nuevoMailer.
Now some basic, initial configuration is necessary to complete your set-up.
Menu > Tools > Configuration & settings
First you will update some basic settings.
- Complete your General settings.
You can leave certain values unchanged for now. But the installation URL is important for further testing.
- Change your Encryption password. Use 8 alphanumeric characters. This password is used to encrypt emails in un-subscribe and other links. After changing this update immediately your administrator accounts.
- Go to Menu > Tools > Administrator accounts and change your administrator account details.
As soon as you change your administrator email, username and password, log out and login again with your new credentials.
Tip: add a second administrator account that you will use only for the cron jobs.
Tip: add yourself both as administrator and subscriber with the same email. In this way you can test
newsletter personalization without sending a full campaign but just s single email.
Create an html newsletter and try to upload an image or an attachment.
Menu > Newsletters > Html newsletters > Create new
If you see the message "Upload failed" then you may want to give write permissions or chmod777 to these folders: assets,
To verify your permissions, test with a small sized file first. Larger files may be blocked due to your php.ini settings.
If you can upload a small file then your permissions are Ok.
Menu > Tools > Configuration & settings: Sending emails
Under Sending emails
define an Email sending method
If you choose SMTP open the SMTP servers window and add an SMTP server. This window is also accessible under
Menu > Tools > SMTP servers
You can learn more about the different sending methods here
Learn how to configure your SMTP servers in the next paragraph
Verify that your email sending method works.
Create a new html newsletter and send a single test email directly from the html editor. If you see an
error or do not receive the email after a few minutes, adjust again at your sending method (or SMTP server).
After you have a working sending method create a mailing list with 1-3 emails of yours.
Create and send a campaign to your test list.
Go to the Summary report and verify that views & clicks are captured.
If not, then check your Views and clicks tracking options in your
Configuration & settings.
Double check also the "installation URL" and repeat your test.
Sending with Amazon SES?
There are two ways to use Amazon SES. Either as an SMTP server or by using the "Amazon SES query api".
The performance is more or less equivalent. But since it depends on yours and your subscribers location it is better to test both and decide.
Attention: your Amazon SMTP credentials are different from your access key id and secret access key.
Menu > Tools > SMTP servers
Using 3rd party SMTP services
nuevoMailer works with all major SMTP-relay service providers such as Mandrill, SendGrid, Mailgun, Amazon SES, Critsend,, AuthSMTP, Mailjet (and many others).
Sending in batches
Menu > Tools > Configuration & settings: Sending emails
|curl -l -s http://www.domain.com/mailer/admin/_start.php?apiKey
|curl -l -s http://www.domain.com/mailer/admin/_start.php?apiKey_c
|curl -l -s http://www.domain.com/mailer/admin/_start.php?apiKey_r
|curl -l -s http://www.domain.com/mailer/admin/_sendTr.php?apiKey
|curl -l -s http://www.domain.com/mailer/admin/_bmProcessCron.php?apiKey
|curl -l -s http://www.domain.com/mailer/admin/dataSourceSync.php?apiKey_X
|curl -l -s http://www.domain.com/mailer/admin/birthdayReminder.php?apiKey
|curl -l -s http://www.domain.com/mailer/admin/_listUnsubProcess.php?apiKey
|curl -l -s http://www.domain.com/mailer/admin/_reset.php?apiKey
|curl -l -s http://www.domain.com/mailer/admin/_optInByEmail.php?apiKey
- For campaigns you will probably have the cron hit every 5 minutes or even less depending on your needs:
*/5 * * * * curl -l -s http://www.domain.com/mailer/admin/_start.php?apiKey_c
- For auto-responders have the cron hit exactly every 5 minutes:
*/5 * * * * curl -l -s http://www.domain.com/mailer/admin/_start.php?apiKey_r
- In case you use one cron job for both auto-responders and campaigns have the cron hit exactly every 5 minutes:
*/5 * * * * curl -l -s http://www.domain.com/mailer/admin/_start.php?apiKey
- For triggered emails a 5 minute period is fine. The frequency should depend on:
- The expected volume of your triggers. If for example you put a trigger on "Campaign view" and you have thousands of views then the _sendTr script should run very often. Even every minute.
- This script processes the emails in batches. And it uses your general batch size defined at your settings page. if needed, you can hardcode the batch size to a number that suits you better.
- However, since the purpose of trigger emails is to target subscribers on an individual and timely basis perhaps it is better to re-evaluate your trigger strategy and instead use a follow-up campaign.
- The birthday reminder should run at least once a day.
- Data source synchronization should be done before a campaign or have it run regularly one or more times per day.
- The bounce manager should run periodically, even several times a day and especially before and
after a campaign so that your lists are cleaned.
Menu > Tools > Configuration & settings: Bounce manager settings
With the bounce manager you are opening and reading a mailbox. So you are interested in what is called incoming
These are usually the same as the ones you use when setting-up an email account in your email client
(Outlook, Thunderbird etc).
Here are the some popular settings that work in most cases.
- For most servers: use ports 110 or 143 and for connection flags use /pop3/notls
- Gmail: use port 993, server imap.gmail.com and for connection flags use /imap/ssl/novalidate-cert
- Important: when you plan to use the bounce manager do not download the bounced emails from the server without leaving a copy at the server.
They must be at the server so that the bounce manager can find them and process them.
Running the bounce manager
You can run the bounce manager manually or with a cron job.
- With a cron job. Refer here for details.
Menu > Tools > Process bounced emails: Click here to process bounced emails
Note: the bounce manager does not automatically delete subscribers from your system.
It simply updates the soft/hard bounce property for each. You can then use the related utilities to process these subscribers:
delete them, suppress them or put them in another list (by doing an advanced search) etc.
Amazon SNS for bounces
When you send your campaigns using Amazon SES (smtp or api) then you must set-up Amazon simple notification services (SNS) in order to process the bounced emails.
Amazon overwrites your <bounce-to> email & settings and adds it's own Return-path header.
We explain here how you can set-up Amazon SNS.
- Grab your endpoint URL from nuevoMailer. Go Menu > Tools > Process bounced emails. At the bottom you see:
The above URL is your Endpoint. Copy it from your own installation!. Replace apiKey with your own by going to Menu>Tools>Administrator accounts>View & edit.
So you have your own Endpoint URL. Now go to Amazon and log in your account.
- Log in to https://console.aws.amazon.com/ with your credentials. Then search for the SNS service. You will see this screen:
Click on Create topic:
In this topic, click on Actions>Subscribe to a topic (or “Create subscription”). This is where you will enter your endpoint.
The system will auto approve the pending verification. It may take a while. Click on Subscriptions to see it:
- Now go to the Amazon SES service (console).
You will create Notifications for the domain but also for the individual email accounts that you have added and verified.
Click on the domain name. Then click "Notifications".
Then click “Edit Configuration”. Use these options that you see below and click “Save Config”.
Repeat step 6 for each of your Amazon verified email accounts. Include/add also the email account that you direct bounces in nuevoMailer.
Click on “Email addresses” then click on the email address and you will see the same screens as in step 6.
Click again on "Notifications" and proceed as in the step 6.
Test your integration
Create a new list and add these email accounts:
Send a campaign to this list. Then go Menu>Reports>View Opt-outs and reasons. You should see this:
How nuevoMailer handles these bounces
- inserts into opt-Outs
- suppresses subscriber
- +1 hard for subscriber
- +1 soft for subscriber
Both above cases
- update campaign bounces+1
- inserts into opt-Outs
- suppresses subscriber
- updates campaign optedOut+1
The provided code is open source. So assuming you know what you are doing feel free to change the above logic to what you want.
Menu > Tools > Configuration & settings: List-Unsubscribe header (optional)
- The "List-Unsubscribe" header is optional but nice-to-have. At the moment it has limited and occasional support by
Gmail and Hotmail.
- This header appends an email address where one can reply and opt-out and/or a direct opt-out link. The
ESP decides what to use.
- This is not a substitute method for unsubscribing. It should not be considered as a replacement to your
normal opt-out links that you must have in your newsletters.
- If the email provider displays the opt-out link and the subscriber clicks it then it will function
exactly as the opt-out link either as global or list opt-out.
- If it shows an email address then the provider will send an email to this address. Therefore you must
"process" this mailbox like you do with bounce manager.
- You must set-up a cron job to process these emails as explained here.
Opt-out by email
Using the above logic and the same process a subscriber can opt-out by sending an email
your "List-Unsubscribe" email account with the word STOP
in the subject. Like this: Example
- You can use the opt-out by email feature without using the "List-Unsubscribe" header.
- But you must set-up the "List-Unsubscribe" mailbox and the cron job so that you can process these unsubscribe emails.
- Using opt-out links in your newsletters is always the best and most direct method.
But there are cases that you send emails or newsletters outside nuevoMailer. In these cases the
opt-out by email is a great trick to use.
Localization for non-English speaking users
You can translate the administration panel into your own language. You will find already some language files which are in admin/includes/lang directory.
In addition, adding your own language involves editing the following files:
See how it is done with another language and replicate it. Remember that the language names and file names are case-sensitive.
To translate the subscriber pages open the file inc/languages.php where you see lines such as:
define("SUBACCOUNT_1", "Your Newsletter subscriptions");
Replicate an existing language block, adjust the $subLang variable and start translating.
Feel free to exchange your translated language files by sending us a copy of your translation.