Mailer

Mailer plug-in throttles emails sent form your WordPress blog, enable SMTP and sender customization.

Please use the support forum to ask questions.

No more problems with providers which set strict limits on the number of emails your account can send per hour! Emails are now stored and delivered slowly even the ones sent by plugins you’re using on your blog (if they uses wp_mail() function, as almost all do).

Mailer perfectly integrate on WordPress 3, there is no need to hack files or configurations. More, it has it’s own SMTP options to use external mail servers.

Just install and activate. This site uses Mailer to throttle emails sent to customers.

Download and discussion

Mailer is freely available on WordPress Plugin Directory and can be discussed on this forum.

Configuration

Default priority

Mailer has a priority system integrated that can be used by other plugins. Priorities go from zero to two, where zero is considered “real time” (emails are delivered suddenly). Mailer intercept all emails sent through wp_mail() function. If a priority is not included in the message, the default priority is assigned.

So, if you want to have emails sent real time if not otherwise specified by the “sender”, set priority to real time (0). If you want Mailer to throttle every emails from your blog, set default priority to “scheduled” (1). Priority 2 is reserved for mass mailing plugins that can full fill the queue: if they set priority too 2, mails with priority 1 is granted to go out as soon as there is a sending slot.

Max emails per hour

It’s the maximum number of email that your provider permits (per hour, if you provider gives a limit per day, just divide it by 24). Mailer takes in account of this setting and avoids to send (per hour) more emails than specified.

Sender

This configuration lets you to force the sender email address and name. When WordPress sends emails it uses as “From” field a fake address like “wordpress@yourdomain.com”. WordPress does that to avoid provider blocks when sending email with domain part not matching the blog domain.

There are three working mode:

  1. Never force sender data
  2. Always force sender data
  3. Preserve non default sender data

Points 1 and 2 are clear. Point 3 makes Mailer to check if the sender was already set externally to something different of WordPress default values to preserve that setting.

If name or email are left empty, they are ignored, so you can decide to force only one.

Return Path

Return path is an email address added to outgoing emails so mail server try to route your email to its  destination have a way to communicate back if something was wrong. Return path, if not specified, is typically added by your provider but if you want to receive error messages it’s best to set it with your email address.

Pay attention: I had experiences with some providers where setting the return path blocked the mail service.

SMTP

If you want to force the usage of an external SMTP to send emails, you can set the SMTP host (name or IP address) and optionally the port (default to 25). Usually external SMTPs require authentication, so you can specify a user name and a password. Leaving SMTP host field blank disable the SMTP functionality.

Using mailer from other plugins

Mailer is automatically used by plugins which call wp_mail() WordPress function. But plugins can pass some information to Mailer to modify its behaviour simply adding mail headers.

Future delivery

If a plugin need to send an email on the future, instead of internally manage such complicate task, it can set the mailer future time calling it before sending the email (The old method with a X-MailerTime mail header is no more valid due to changes on WordPress 3.2).  Just an example: we want to send an email between two days. A day has 3600*24 seconds. So wp_mail() can be called as:

Easy, isn’t it?

Priority

Plugins which send out a lot of emails may create a great delay to other emails (like a comment notification). Those plugins can set a priority on their emails setting it befor stating a sending batch (o before sending every single email). The old method that used the X-MailerPriority is no more valid due to changes on WordPress 3.2. May be you know there is a “priority” concept in emails driven by some special header like “Importance” or “X-Priority” but they are specific to the email delivery process from the sender to the receiver, this is why I prefer to not use them as priority indicator on Mailer plugin.

Example:

Priority order is: 0 – real time, 1 – normal, 2 – low priority. Messages sent without specify a priority (as did by WordPress) get the default priority specified on configuration. Massive mail plugins (like newsletters and mailing lists) should use a priority of 2.

Groups

To identify emails sent by a plugin, a special header can be added (plugins have to take care of that) with a “group name”, a single word with no spaces or symbols. The group must be a single string with no spaces or special characters (so use a to z and 0 to 9). As for priority the base example is:

where “newsletter” is the group name. This help the blog owner that want to real time delete some outgoing emails to better identify them and remove them with an FTP client. When a group is specified, files representing outgoind emails (or the sent one) will get the format:

Frequently Asked Questions

Does exist a list of compatible plugins?

Yes.

  1. File Commerce Pro
  2. Newsletter (this does not really need Mailer plugin to throttle emails)
  3. Comment Plus

Those plugins uses the services of Mailer. Other plugins or WordPress it self benefits from Mailer as well.

Does Newsletter plugin benefits of mailer?

No, Newsletter plugin has its own throttling system. But they are compatible.

Does mailer introduce delay on outgoing emails?

Yes, of course. If there are no other emails on queue, the maximum delay will be 5 minutes (but read more about WordPress cron below). In future versions there will be a smarter delivery system that will send real time if the queue is empty and a priority system will be implemented.

Where are the email stored and why you don’t use the database?

Provider not only have emails per hour limits, memory limits, script execution time limits, they sometime set queries per hour limits. If you have a plugin which do mass mail (for example a membership or a subscription plugin), if emails would be stored on database Mailer needs to make an incredible number of queries in a very little time, may be generating fatal errors (which means all will be lost).

Email are store in an semi-readable format on the folder “wp-content/mailer” and sub folders.

I have some warnings about files/folder permissions on configuration panel

Be sure the Mailer was able to create the folder “mailer” inside “wp-content” and the inner folders “sent”, “out”, “error”. If those folder are missing, create them by hand. On first part of Mailer admin panel there is a “system check” which should report any of that problems. Pay particular attention to have the mentioned folders write enabled.

There is any housekeeping process on stored email (sent and unsent)?

Actually not, just empty the _sent folder from time to time.

How can force the cron execution on my low traffic blog

If your provider supply the cron configuration (many do), you can use a command like that:

to be executed every 5 minutes. If your blog is installed in a sub folder, the address will be:

Where can I find error logs?

On wp-content/mailer folder there is a errors.txt file with errors. Every line on that file refers to an  email Mailer was not able to send and that it copied on “error” folder.

Can I reschedule emails with errors? And when it’s a good practice to do that?

To reschedule one or more emails with a previous sending error condition, simply move their file from “error” folder to “out” folder. When it’s a good idea to reschedule emails? For example when the error was an SMTP connection error, if you configured an SMTP. The mail library used do not report error codes, so actually I cannot distinguish between kind of errors and auto reschedule the emails with particular error condition.

There is any kind of bounce management?

Actually not.

How can I check if the plugin is installed to use from my plugin?

Probably the best way is to check if the Mailer class exists:

To directly call the plugin method, DO NOT instantiate the class, bu use the global variable “$mailer” even if actually there are no method of “public utility”.

What about memory limit or execution time out?

Mailer, while sending a group of emails, tries to raise the memory limit to 256 megabytes, as done by WordPress when you use the administration side of your blog. Some providers do not allow the memory upper limit change but most do. I don’t think Mailer needs a really big amount of memory but for safeness I added such upper limit change. Keep in mind that memory used really depends on the number of messages sent per cycle.

Execution time out is more delicate: even when a provider lets to change and increase the PHP execution timeout, external process can stop the script if it runs for too much time (is a typical configuration of CGI, FastCGI or FCGID). So, increasing the execution timeout can be as risky as ignore it. Mailer implements an internal control on time out and, while sending, tries to stop it self if the execution is taking too much time.