Installation and configuration

Inside your nuevoMailer zip package you will find the setUp.html which explains how to install/upgrade nuevoMailer.
In short, you create a database with a user and a password at your server, put these details in your settings file and upload your files to the server.
Then you follow the installation wizard (using your browser) to create the tables.

In the package

  • admin: Contains the files that you (the administrator) will use to operate the application.
  • api: contains all api versions from 1 to 4.
  • assets: this is where your newsletters images (html templates, zipped templates) are stored. The html editor has a file manager that enables you to upload and insert images in your newsletters.
  • attachments: this is the folder for your newsletter attachments. 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.
  • 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/upgrading. You should remove this folder after you have completed your installation.
  • subscriber: contains the public pages that your subscribers use.
  • plugins:
    - WordPress plugin: Read here about ways to bridge nuevoMailer and WordPress.
    - SalesForce plugin. Demonstrates how to connect to SalesForce, query your SF tables and insert subscribers in nuevoMailer. It is provided as proof of concept and further development is required for tighter integration.
    - BEE editor plugin. Loads the BEE editor inside nuevoMailer. You must register your own account. For installing and activating refer to the how-to-install file inside the beefree folder.
  • 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 web.config file is the equivalent and only needed for Windows servers.
  • zip-templates: contains zipped html templates with images. The html editor has a utility to upload zip files and/or extract them and automatically create newsletters.

Key concepts

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 sent 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.

Basic configuration

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. Then update immediately your administrator account passwords.
  • 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 a single email.
  • Create an html newsletter and try to upload an image or an attachment.
    Menu > Newsletters > Html newsletters > Create new
    Since v.8.6 the file managers alert you about folder write permissions and the maximum file size allowed when uploading. For earlier versions read below.
    If you see the message "Upload failed" then you may want to give write permissions / chmod755 to these folders: assets, attachments, data_files. In some cases chmod777 may be required.
    To verify your permissions, test with a small size 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. But if you cannot upload a larger file then you are probably exceeding the allowed limit on our PHP settings.

Administrator roles

Menu > Tools > Administrator accounts > View & edit
  • The first and default admin account with ID 1 cannot be deleted, neither edited by other administrators and has access to all features and options. Let's call this Master account.
  • If needed you can open more administrator accounts and limit their access to specific sections of the administration panel.
  • Important: if an administrator has access to Tools then he can create and edit other administrator accounts except the Master account.

Email sending

Define the Email sending method.
Menu > Tools > Configuration & settings: Sending emails
You can learn more about the different sending methods here.
With SMTP open the SMTP servers window and add an SMTP server: Menu > Tools > SMTP servers.
Learn how to configure your SMTP servers in the next paragraph.
If not using SMTP you will see two other options:
  • Throttling / Maximum send rate (Global)
    You can use 0 for unlimited (meaning as fast as the server can send).
  • Email account to send bounces (Return-path):
    This defines where bounced emails will go. So you should add a bounce server to process this mailbox. Go to:
    Menu > Tools > Bounce manager settings > Bounce servers
    If using Amazon SES, SendGrid or MailGun, bounces and complaints are processed with webhooks and there is no need to define a mailbox for bounces.
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).
Create and send a campaign to your test list
After you have a working sending method create a mailing list with 1-3 emails of yours.
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.

SMTP servers

To use the SMTP sending method go to Menu > Tools > Configuration & settings: Sending emails and select SMTP.
Then go to Menu > Tools > SMTP servers
Click "Add new smtp server". Enter the server name or ip and click "Add".
Then continue by clicking the "Edit" icon .
You can define as many smtp servers as needed. Only active smtp servers are used. Temporarily you may choose to de-activate a server instead of deleting it. At least one server should be set as -Preferred- and it will be used when sending single emails (welcome, goodbye etc). To test an smtp server set it as -Active- and -Preferred- and send a test newsletter from the newsletter form.
You can also test the smtp connection by clicking this icon . Save your changes first.
  • Continuous SMTP rotation / Load balancing
    When enabled each batch is spread evenly among the available SMTP servers. When not, SMTP servers rotate with every new batch.
  • Bounce server: each smtp server may use its own bounce server.
    So in this drop-down you will see a list of all your bounce servers for which you have a Return-path defined.
    The Return-path is simply an email account/mailbox. When defined, it adds an email header that tells the server where to send an email that bounces.
    You will see it in the email headers like this: Return-Path: <>.
  • SMTP anti-flood: close the smtp connection after sending X emails and pause for Y seconds.
    Some smtp servers may have a limit on the number of emails you can send during a single smtp connection.
    The purpose of smtp anti-flood is to close and reopen the smtp connection after sending a number of emails.
    Smtp anti-flood happens inside a batch. So the values you use should be considerably lower than the batch settings.
    Typical values may be:
    First consider your smtp provider requirements. They may have specific instructions for these values.
    Number of emails can be anything between 10-100 emails. The pause can be 5 seconds or more.
    You should set these values in relation to your batch settings.
    To disable smtp anti-flood use 0 for both values.
    Using smtp anti-flood improves your deliverability.
  • Throttling / Maximum send rate
    Especially useful when using Amazon Simple Email Services (SES).
    To de-activate/disable enter 0.
  • Available for All campaigns - Selected lists
    When you use custom list settings and you want to make sure this smtp server will only be used in campaigns to these lists select Selected lists.
  • When you change the availability of an smtp server from Selected lists to All campaigns it is automatically removed from the lists it was assigned to. The same happens when you delete it.
  • Daily maximum limit: Enter 0 for unlimited. If you use this you should also create the cron job #10 to _reset.php that runs only once a day (just before midnight or any time you want to reset the limit).
    When the daily limit is reached this smtp server cannot be used in any campaigns until the limit is reset.
  • Total sent (since last reset): this is a counter.
  • Custom headers (optional)
    Some SMTP providers may require you to add some custom email headers in your emails.
    You can add custom headers in this manner. One header per line and end with a semicolon ;
    In the example below the last two lines will be replaced with the subscriber and campaign IDs.
    For subscriber data you can use practically any personalization smart tag that you use in a newsletter.
                Header-field-1 => value-1;
    Header-field-2 => value-2;
    X-MC-Track => clicks_textonly;
    X-Message-Info => value;
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).

Bounce servers

Menu > Tools > Bounce manager settings > Bounce servers
A bounce server is a mailbox that collects the bounces resulting from your campaigns.
When you process bounces you are in fact opening and reading this mailbox.
So the settings you will use are what we call incoming mail settings. These are usually the same as the ones you use when setting-up an email account in your email client (Outlook, Thunderbird etc).
With nuevoMailer v.8.6 you may define several bounce servers and you can tie on more smtp servers to a specific bounce server.
Click "Add new bounce server", enter the server address (name or IP) and you will continue with more details.
Automatic suppression: if any of these conditions is met then the subscriber is automatically suppressed.
Normally one hard bounce or complaint should be enough to justify a suppression. A hard bounce can be false sometimes so you can use 2 or 3. For soft bounces you can use a larger number.
Click on the "Edit" icon to continue with more details.
You can test a connection by clicking this icon . Save your changes first.
It is your mailbox provider that will tell you what settings to use.
Here are the some popular settings that work in most cases:
  • Most servers will use ports 110 or 143 and for connection flags /pop3/notls
  • For imap/secure connections use port 993 and connection flags /imap/ssl/novalidate-cert
  • For "Options" always use OP_SILENT unless specifically instructed otherwise.
  • Gmail settings: port 993, server, connection flags /imap/ssl/novalidate-cert
  • The Return-path is usually the same as the Pop3/Imap email/username. Without a Return-path this bounce server is not included in the processing.
Important: in order to process the bounced emails do not download them 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.
Processing bounces
You can do it manually or with a cron job.
  1. With a cron job. Refer here for details.
  2. Manually:
    Menu > Tools > Bounce manager settings > Process bounced emails
    In this page you will also find several utilities for cleaning up your subscribers.
Tthe 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.
Not using SMTP?
In case you use SendMail, PHP-mail or Pick-up (PowerMTA) you will see another option in your general settings: Enter here the mailbox where you want to send the bounces and create a bounce server (having the same Return-path) to process it.

Sending in batches

It is highly recommended to use batches when sending. It improves deliverability and eases the strain on the server.
Menu > Tools > Configuration & settings: Sending emails
  • These settings are used when sending manually using a pop-up window.
    The pause (batch interval) works as an exact pause. You will see your pop-up window reload exactly after the pause.
    You can use any number of minutes for pause or 0 or fractions of a minute: 0.5.
  • When sending with cron you can set the batch settings specifically for a campaign.
    With cron, the pause (batch interval) works as a minimum safe distance between two batches.
    You can use 0 for pause and let the cron period regulate the timing (unless of course you have more specific requirements).
    A rough example:
    Assume your cron hits every 5 minutes. But for this campaign you want to have at least 10 minutes break before the next batch starts.
    So you use 10 minutes for pause. In your log file you may see lines similar to this:
    Task: 3-->2014-12-15 16:27:24-->Check-point-5.-->STOP. Time since last execution: 9 Batch pause: 600.0
    In other words: only 9 seconds elapsed since the last batch finished. But the pause is 10 min (600 secs). So it will stop now and it will check again with the next cron run.
  • Always use batches except perhaps for small campaigns like auto-responders (or recurring campaigns).
    Batches can help you improve your deliverability.
    Batches ease the load on the server especially when sending to large lists.
    In such cases using batches will actually result in faster sending.
  • Batches can help you conform with your Host's quotas (the amount of emails you can send in a given time-frame). Consult with your Host or SMTP provider to find these quotas.

Cron jobs

There is no need to add all of the cron jobs that you see below. Most of them refer to special features which if you don't use then you don't need their cron jobs.
Jobs 2 & 5 are the most important ones that most users will probably need.
Attention: do not add both 1 & 2 & 3.
Add only job 1 or 2 & 3 (in case you have heavy loads of campaigns and autoresponders and need to use different timing for each).
1 For both campaigns and auto-responders (v.4/5/6.x/7.x/8.x) curl -l -s
2 For campaigns only (v.6.x/7.x/8.x) curl -l -s
3 For auto-responders only (v.6.x/7.x/8.x) curl -l -s
4 Trigger & transactional emails (v.5/6.x/7.x/8.x) curl -l -s
5 Bounce manager (v.4/5/6.x/7.x/8.x) curl -l -s
6 Single data source synchronization (v.4/5/6.x) curl -l -s
7 All data sources synchronization (v.7.x/8.x) curl -l -s
8 Birthday reminder (v.4/5/6.x/7.x/8.x) curl -l -s
9 List-Unsubscribe (v.4/5/6.x/7.x/8.x) curl -l -s
10 To reset the daily maximum limit in all campaigns (& smtp servers) (v.6.x/7.x/8.x) curl -l -s
11 Subscribe by email: read & process mailboxes (v.6.x/7.x/8.x) curl -l -s
12 Feedback loop (v.8.x) curl -l -s
  • Replace with your own installation URL.
  • Instead of curl -L -s you may use WGET -O /dev/null.
  • Replace apiKey with your own.
    You will find your api key in your administrator accounts page:
    Menu > Tools > Administrator accounts
  • For v.4/5/6.x, when syncing a data source X is the ID of the data source you want to sync.
    You can see this ID in the drop-down menu where you select a data source (external database connection).
  • Need help with timing syntax?
    You can refer here for details.
    You may also use this free service to create your cron command
  • Attention: your api key is derived from your administrator email and encryption password.
    If you change any of these two then you must copy the new api key and update your cron jobs.
  • For campaigns you will probably have the cron hit every 5 minutes or even less depending on your needs:
    */5 * * * * curl -l -s
  • For auto-responders have the cron hit exactly every 5 minutes:
    */5 * * * * curl -l -s
  • 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
  • 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 job #4 should run very often (every 2 minutes).
    • 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 per hour and especially before and after a campaign so that your lists are kept clean.
  • Feedback loop: more here.
Are my cron jobs running?
Check your activity log to confirm that your cron jobs are set correctly and running.
Menu > Campaigns > Activity log
You should see lines there like Cron hit and similar.

Amazon SNS for bounces / complaints

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.
  1. Grab your endpoint URL from nuevoMailer. Go Menu > Tools > Bounce manager settings > 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.
    Make sure that the Api key is from an active administrator account.
    So you have your own Endpoint URL. Now go to Amazon and log in your account.
  2. Log in to with your credentials. Then search for the SNS service. You will see this screen: Click on Topics at the left side menu and then click the orange button at the right side Create topic.
  3. Create topic
    Under Details enter a name for this topic. Leave all the rest as-is and click the orange button Create topic at the bottom of this screen.
  4. Create a subscription for this topic
    As soon as you create your topic you will see this screen:
    Click the Subscriptions tab and then the orange button Create subscription. This is where you will enter your endpoint.
    Choose either HTTP or HTTPS depending on your installation. Click the orange button Create subscription at the bottom of the screen to save it.
  5. The subscription will initially appear as Pending verification.
    The system will auto approve it and change it to Confirmed.It may take a while.
    On the left side menu click Subscriptions to see it: If confirmation is taking longer check your log file to see if something went wrong with your endpoint: Menu > Campaigns > View log file.
    In case you correct something and make changes click on the "Request Confirmation" button.
  6. 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”.
  7. Repeat step 6 for each of your Amazon verified email accounts. Include/add also the email account that you direct bounces in nuevoMailer (not required for v.8.6).
    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.
  8. Test your integration Create a new list and add these email accounts:
    Send a campaign to this list. Then look at your complaints, bounces and opt-outs reports. You should see entries like:
  How nuevoMailer handles these events
    Permanent bounce
  • Inserts into Opt-outs
  • Suppresses subscriber and updates his hard bounces
  • Removes subscriber from all lists
    Soft bounce
  • Updates subscriber with a soft bounce
    Both above cases
  • Updates campaign's bounces
  • Inserts into bounces table
  • Suppresses subscriber and records the complaint
  • Inserts into Opt-outs
  • Removes subscriber from all lists
  • Updates campaign's opt-outs and complaints
  • Inserts into Complaints table

MailGun webhooks

If you use MailGun smtp then you can set-up Webhooks in your MailGun panel and receive notifications for these two events: failures (bounces) and spam complaints.
First add this custom header to your MailGun smtp server in nuevoMailer:
X-Mailgun-Variables=> {"recipient_id": "[sub_id]", "campaign_id": "[camp_id]"};
Copy-paste exactly what you see above.
Then prepare your Webhook URL. This is:
Replace with your own domain, path and apiKey (from your nuevoMailer administrator accounts). Write it down.
Inside your MailGun panel click on "Sending" and then on "Webhooks".
First test your URL. Choose "Event type" Permanent failure. You will know if it worked. At the same time log in your nuevoMailer and go Menu>Campaigns>View log file.
After testing click on the "Add Webhook" green button and add 3 webhooks for these event types:
Permanent Failure
Spam Complaints
Temporary failure
  How nuevoMailer handles MailGun events
    Permanent bounce
  • Inserts into Opt-outs
  • Suppresses subscriber and adds a hard bounce
  • Removes subscriber from all lists
    Soft/temporary bounce
  • Adds a soft bounce for the subscriber
    Both above cases
  • Updates campaign bounces
  • Inserts into Bounces table
  • Inserts into Complaints table
  • Suppresses subscriber, records the complaint
  • Inserts into Opt-outs table
  • Updates campaign's opt-outs and complaints
  • Removes subscriber from all lists

SendGrid webhooks

New since 8.5
If you use SendGrid smtp then you can set-up Webhooks in your SendGrid panel and receive notifications for these two events: bounces and spam-report.
Add this custom header to your SendGrid smtp server in nuevoMailer:
X-SMTPAPI=> {"unique_args":{"recipient_id":"[sub_id]","campaign_id":"[camp_id]"}};
Copy-paste exactly what you see above.
Then prepare your Webhook URL. That is:
Replace with your own domain, path and apiKey (from your nuevoMailer administrator accounts). Write it down.
Inside your SendGrid panel open "Settings" > "Mail Settings" and proceed as in the pictures below.
For a lengthier explanation check this article.
Enter your Webhook URL below:
Enable the webhook:
  How nuevoMailer handles SendGrid notifications
    Permanent bounce
  • Inserts into Opt-outs
  • Suppresses subscriber
  • +1 hard bounce for the subscriber
    Soft/temporary bounce
  • +1 soft bounce for the subscriber
    Both above cases
  • Updates campaign bounces+1
  • Inserts into Bounces table
    Complaint / Spam Report
  • Inserts into Complaints table
  • Inserts into Opt-outs table
  • Suppresses the subscriber and removes him from all lists
  • Updates campaign's opt-outs and complaints

Feedback loop / Complaints

Menu > Tools > Configuration & settings: Feedback loop settings (optional)
  • In order to use this feature you must register with major ISPs in order to receive notifications by email about subscriber complaints.
  • Create an email account specifically for this purpose. ISPs will send you email notifications to this email account.
  • You will also need to add this cron job so you can process the mailbox:
    Replace with your own domain, path and apiKey. Have the cron job run several times per hour and keep the "Number of messages to process in a single run" below 100.
  • There is no definite standard as to what content exactly each ISP will send you back. If possible you should ask to receive the original email you sent (attached) or its headers.
  • nuevoMailer will scan the email and try to extract subscriber and campaign information. Do not download the emails from the server. Or if you do, leave a copy there. nuevoMailer will delete them after processing.
  • This is what nuevoMailer will do with these emails:
    1. Update campaign complaints+1
    2. Remove subscriber from all lists in this campaign
    3. Insert subscriber into opt-outs for all lists in this campaign
    4. Update subscribers complaints+1 & mailDeliveryInfo='FBL complaint'
    5. If the complaints threshold for this subscriber is reached:
      - suppress subscriber
      - remove from all lists
      - insert into opt-outs as a global opt-out and reason 'FBL complaint'.

"List-Unsubscribe" header

Menu > Tools > Configuration & settings: List-Unsubscribe header
  • The "List-Unsubscribe" header is optional but nice-to-have. At the moment it has limited and occasional support by major ESPs/ISPs.
  • 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 cron job #9 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 to 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

  • All users are strongly recommended to use utf8 character encoding which is a safe choice for all languages.
    The script you used to create your tables defines also the Global character set you must use in your configuration settings.
    So use an equivalent encoding: both in utf8 or latin1 with iso-8859-1/3.
  • Always define the character set at the newsletter level (with the same logic as above).
  • It is a good idea to define the character set for the landing pages & greeting emails (welcome, goodbye etc) by adding such a line in the html code:
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8858-1">
You can translate the administration panel into your own language. You will find the language files in the directory /admin/includes/lang/.
In addition, adding your own language involves editing the following files:
  • /admin/includes/languages.php
  • /admin/index.php
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.
© 2021 Designerfreesolutions
Visit the Demo