Mailer Configuration

Home>Mailer>Configuration Instructions

Introduction

The TegoNuke™ Mailer comes with its own database table to store its configuration settings as well as an system administration module to manage those settings. You must log into your *nuke site with an Admin user that has SuperUser capability so that the link/icon at the left is visible. Just clicking on that TegoNuke Mailer link/icon will bring up its admin module.

Configuration settings are grouped into three major groups:

1. Activate Mailer - this is where the Mailer can be switched on or off
2. General Mailer Options - this is where the send method is chosen and other Mailer-wide settings are entered
3. Send Method Options - depending upon which send method is chosen, a different set of settings are presented for entry

Each of these setting groups are explained in more detail below, but first some general administration module usage aids.

General Administration Module Usage Tips

At the top of the administration module (see below graphic), there are two links worth mentioning. The first is the Site Administration link. When this link is clicked it takes you back to the main *nuke Administration Control Panel. The second link titled About TegoNuke Mailer takes you to the module/hack credits.

The TegoNuke™ Mailer comes with extensive help text built right into the on-line administration module. If you hover your cursor over the white-on-red-background icon that is next to any of the configuration options, a little window pop-ups with descriptive help text. For example, if you hover your cursor over the sample given at the top, your cursor changes into a large question-mark and the text should look like this:

Now onto detailed explanation of each of the available options.

Activate Mailer Settings

The main Activate Mailer Settings section looks like this:

Choosing No essentially disables the Mailer and the code will just revert back to the original *nuke core mail code. Choosing Yes enables the Mailer and it will use the current enabled settings (see below).

It would be best to enter all your desired configuration settings first and then activate the mailer. You may also wish to complete all your core file edits (see installation/upgrade instructions) prior to activating the mailer - not necessary, just a suggestion if you are extra paranoid.

General Mailer Options

This section of options apply to the entire Mailer and it looks like this:

The Send Method is what will control how the mailer will send email and make the appropriate options for the chosen method accessible from drop down lists. If you choose SMTP, you will have the opportunity to enter your SMTP server URL and port as well as whether you wish to use authentication and/or encryption; these options will be explained in far more detail below under the SMTP Configuration Settings.

NOTE: Authenticated and encrypted SMTP is the recommended setup as long as your web host provides for these two connection/send options. You will need to check with your host to find out what client connections are allowed (more on this below under the SMTP-specific settings).

If you are not able to use SMTP, either Sendmail or PHP Mail() options are your only other options. To be quite honest, these options really should not be needed for a real hosted environment. However, if you need them, they are there.

An Email Bounce Address setting is available for your use. If this setting is left blank, no Return-Path address will be provided on your email sends. Most web host accounts (at least the non-free ones) will allow you to set up more than one email address. It is recommended that you set up a separate email account to collect your bounced emails. If you follow this recommendation then enter that email address here. This way, you can check on that email account, after a large batch send for example, and see which of your *nuke user's email addresses are no longer valid. Sound useful? We thought so... ;-) For ANY email address you set up, make sure it is from your domain. The author of the Swift Mailer library has an excellent article entitled How to (legitimately) minimize being seen as spam that we highly recommend you reading if you plan on doing a lot of email sending.

The TegoNuke™ Mailer provides extensive debug messaging capabilities as well as error catching. The Debug Level setting is where you would come if you were experiencing issues with your email sending through the Mailer or would like to test everything right up through the email connection, but just not perform the final send. The default setting is OFF where all errors and debug messages are suppressed.

If you set this to ON, WITH SEND, a logged in admin (and ONLY a logged in admin, no-one else will see any messages), will see comprehensive messages on the returned web page at every stage of Mailer operations. Use this option if you are not getting email messages being sent/received. If you would like to see all the error and debug messaging right up through the mail server connection but do not want the actual send to take place, use the ON, NO SEND option setting.

Once you have configured these settings, you are ready to fill out the settings for your chosen Send Method (SMTP and Sendmail only as PHP Mail() has no additional settings).

Send Method Options

SMTP Configuration Settings

The SMTP send method is the recommended option. With it, you will be able to take advantage of settings and facilities available on most web hosts including authenticated SMTP and connections encrypted with SSL or TLS. You will need to make sure that these settings are available on your web host first, of course. The configuration settings for this send method look like this:

Most web hosting accounts will provide some form of "control panel" where you are able to add mail accounts, set mail account passwords, and to see what your client connection settings should be. If none is provided, you will have to check with your web host as to what are the proper settings.

For example, cPanel is one such control panels, and under the Mail settings section, there is an icon like the one at the right. Next to the mail account there is an option to Configure Email Client. Under there, you are looking for these types of settings:

• Mail Server Username:
• Outgoing Mail Server:
• Supported Outgoing Mail Protocols: SMTP, SMTPS (SSL/TLS)

Each of the configuration options are described next in more detail and the above sample settings will be referenced as well to help you get the configuration right. Keep this in mind: think of this as if you were configuring an Outlook or Thunderbird or any other mail client, and configuring the client's ability to send mail through that mail account with your hosting provider.

• Server - this is the Outgoing Mail Server that your mail account is on. It is the SMTP outgoing server.
• Helo - this is usually the same as the Server. If making these the same does not work, check with your web host as to the proper Helo value.
• Port - this is the port that the connection needs to be made to. For non-encrypted connections, the default is usually 25. For encrypted connections, the port is usually 465. The Outgoing Mail Server line above in our example will usually have the port number tacked onto the end and there will be two lines, one for non-encrypted (if available) and the other for encrypted (if available).
• Authentication - most web hosts will require that you use an authenticated connection (our default), and you will need to provide both the Username and Password from your outgoing mail account for this. If you are not going to use authenticated SMTP, simply click on the No option and leave the Username and Password fields blank. NOTE: the Username can be a little bit tricky. If you were able to log into your control panel and get the exact format to use, great, use that. But, if you do not have the exact format, you could try either user+yourdomain.tld or just user or maybe user@yourdomain.tld. If none of these work, you'll need to check with your web host for the proper values to use.
• Use Encryption - if your web host provides this for your account, we would highly recommend using it, especially if your *nuke site runs on a different server than your mail server. Yes, that is right, it is possible to run these are different servers and in fact, this is how one can run a local copy of your site on your PC/laptop and still be able to test email sends! If you want to use encryption, select the Yes option and then select your Encryption Method. If you do not want to use encryption, then select the No option (no need to modify the Encryption Method setting). Make sure you use the right port above if you are using encryption.
• Encryption Method - if you have elected to use encryption, you will need to choose either SSL or TLS. Either one is fine, just choose the one that is available for your web host's Supported Outgoing Mail Protocols. Our preference would be TLS over SSL.

At this point, you should be done configuring your SMTP settings and you could activate the Mailer and perform a test send (see below section entitled How to Test Your Configuration).

Sendmail Configuration Settings

The Sendmail configuration settings look like this:

In most setups the default location for the Sendmail daemon will work. If it does not, you may need to check with your web host as to the correct location of the binary as well as any needed command line options to be passed. The bottom line is that this setting requires the absolute path to the sendmail binary in order to work properly.

The Sendmail open source community is very strong. If you need to use this method of sending emails (highly doubtful) and you run into any issues with how it is set up, it is possible that the community could help. Extensive documentation also exists on the provided site link.

NOTE: although we have not tried, it may also be possible to use Sendmail under-the-covers so to speak, if your host or environment allows it, by configuring the mailer to use SMTP and use localhost (or its IP address) and port 25 IF the Sendmail daemon is set up to accept these types of connections. However, most hosting providers and even internal company policies may refuse this type of set up as there are many known exploits to the Sendmail daemon.

At this point, you should be done configuring your Sendmail settings and you could activate the Mailer and perform a test send (see below section entitled How to Test Your Configuration).

PHP Mail

So, why are there no specific settings for the PHP Mail() option? Well, quite frankly, there just aren't any special options/settings required. So why use the TegoNuke™ Mailer PHP Mail() option as opposed to the existing core mail() feature within *nuke? The TegoNuke™ Mailer gives you the ability to use an email bounce mail address and also the ability to debug your mail issues.

Just so it is clear, this option has not been tested extensively as the recommended send method is authenticated and encrypted SMTP. There are also Swift Mailer forum threads which document PHP configuration deficiencies of web hosts which may cause the Mailer not to function properly or could even result in being flagged as a spammer on some ISPs (due to poor php.ini configuration on outgoing emails).

How to Test Your Configuration

The absolute easiest way to test your TegoNuke™ Mailer configuration settings is to activate the Mailer and use the *nuke Feedback module to send you, the admin, a test feedback comment. If everything is configured properly (and your core file edits for this module are correct), you should have a Feedback message in your admin's email account after a bit. You can even check the email headers using your email client to see if all the appropriate From, To, Reply-To, and Return-Path (only if you elected to configure the Email Bounce Address) headers are correct.

If you would like test a batch send email, like what the Newsletter module does, it gets a bit more complicated. If you are using the HTML Newsletter module from Montego Scripts with the NSN Groups hack installed (these are already embedded in RavenNuke™), you could create a couple of dummy users with valid email addresses, assign them to a NSN Group, and then use either the HTML Newsletter or the NSN Group administration Send to Group feature to perform a batch send to this "dummy" test group. Each user in the group should get a separate email directly addressed to them (i.e., only one email address on the To line) with all the correct email headers.

Language Configuration

The TegoNuke™ Mailer does support the native *nuke method of providing different literal language translations provided that a language file for your desired language is available. As of this writing, the list of supported languages is rather small.

If you would like to provide a translation for a specific language feel free to communicate as such through the various feedback/forum/PM options available at Montego Scripts. To create a new translation is easy. Copy the existing lang-english.php script from language/tegonuke/mailer to a new lang-xxxxxxxxx.php file replacing the x's with the language name and start translating the text in that new file accordingly.

Warranty/Disclaimer

Review Mailer Warranties and Liabilities. We're serious about this. Use at your own risk and respect those whom you send to. Don't SPAM!