Sugar Mailer

This is a little mail plugin that contains:

• SMTP plugin wrapper
• easily send plain text, html or both text & html hybrid content mails
• convenient methods to add one or multiple recipients
• encode special chars for mails with ISO charset
• ping and jump methods for tracking read and click events in your html mails
• save mails as files to disk

Getting started

This plugin is configurable via config file:

[mailer]
; smtp config
smtp.host = smtp.domain.com
smtp.port = 25
smtp.user = [email protected]
smtp.pw = 123456789!
; scheme could be SSL or TLS
smtp.scheme =

; optional mail settings
from_mail = [email protected]
from_name = Mario Bros.
; mail to receive bounced mails
errors_to = [email protected]
; used mail for replies to the sent mail
reply_to = [email protected]

; handler for SMTP errors
on.failure = \Controller\Mail::logError
; handler for tracing opened mails
on.ping = \Controller\Mail::traceMail
; handler for redirecting jump links
on.jump = \Controller\Mail::traceClick
; automatically create jump links in all <a> tags
jumplinks = true
; path for storing mail dumps
storage_path = logs/mail/

Usage

A little sample looks like this:

function send_test($email, $title=null) {
	$mail = new \Mailer();
	$mail->addTo($email, $title);
	$mail->setText('This is a Test.');
	$mail->setHTML('This is a <b>Test</b>.');
	$mail->send('Test Mail Subject');
}

If you want, you can change the encoding type that is used for the email body and header when instantiating the mail object with a constructor argument:

$mail = new \Mailer('UTF-8'); // default
$mail = new \Mailer('ISO-8859-1');
$mail = new \Mailer('ISO-8859-15');

Tracking

To initialize the tracking routes, call this before $f3->run():

$f3->config('mailer_config.ini');
// ...
Mailer::initTracking();
// ...
$f3->run();

To add the ping tracking pixel (1x1 transparent 8bit PNG), put this in your html mail body:

<img src="http://mydomain.com/mailer-ping/AH2cjDWb.png" />

The file name should be a unique hash you can use to identify the recipient who read your mail.

The tracking methods could look like this:

static public function logError($mailer, $log) {
	$logger = new \Log('logs/smtp_'.date('Y_m_d').'.log');
	$logger->write($log);
}

static public function traceMail($hash) {
	// your mail $hash is being read
}

static public function traceClick($target) {
	// someone clicked $target link
}

Mock & Storage

In case you don't want to actually send the email, but just want to run a test flight and save the mail in a text file, you can mock the server dialog:

$mail->send($subject, TRUE); // mock call 
$mail->save('newsletter.eml'); // save to file in 'mailer.storage_path' directory
$mail->reset();

If you want to keep using the object after a mock call, you need to reset the mailer and add recipients, content and attachments again.

The mail file includes all file attachments.

Logging

You can log the full SMTP server dialog after sending the email. This could be useful for debugging purposes or as a sending confirmation.

$success = $mailer->send($subject);
$f3->write('SMTP_mail.log', $this->mailer->log());

Notice: By default, the log level is verbose, which means it also contains the mail body and attachments, which might eat up a lot of memory. To reduce the log level, set $log to TRUE (dialog only) or FALSE (disabled) in:

$mailer->send($subject, $mock, $log);

Keep in mind that when you write down mails to files, it can only store what was found in the SMTP log, hence it only works when logging level is verbose.

Demo & Testing

There's a test bench available here: https://github.com/ikkez/f3-mailer/tree/test

API

addBcc

Adds a blind carbon copy recipient.

addBcc($email, $title=null)

addCc

Adds a carbon copy recipient.

addCc($email, $title=null)

addTo

Adds a direct recipient. addTo($email, $title=null)

attachFile

Adds a file attachment.

attachFile($path, $alias=null, $cid=null)

initSMTP

Initializes SMTP plugin. Useful if you want to reuse the Mailer object but with a fresh SMTP adapter beneath. It's possible to change options before, i.e. to use a different smtp server.

initTracking

This registers the required routes to F3

log

Returns SMTP log

reset

Reset recipients if key was given, or restart whole smtp plugin.

($key=null)

save

Save the send mail to disk

save($filename)

send

Send message

send($subject [, $mock = false [, $log = 'verbose']])

log level options: FALSE, TRUE, 'verbose'

set

Set encoded header value

set($key, $val)

setContent

Set message contents by mime type

setContent($data [, $mime [, $charset=NULL ]])

I.e. for AMP mails:

$mailer->setContent($amp,'text/x-amp-html');

setErrors

Set receipient for bounce error mails

setErrors($email [, $title=null])

setFrom

Set message sender

setFrom($email [, $title=null])

setHTML

set message in HTML text format

setHTML($message)

setReply

set reply-to field respected by most email clients

setReply($email [, $title=null])

setText

set message in plain text format

setText($message)

License

You are allowed to use this plugin under the terms of the GNU General Public License version 3 or later.

Copyright (C) 2022 Christian Knuth [ikkez]