wedeto/mail

Wedeto Platform - SMTP Mailer

v1.0.0-beta2 2018-06-14 21:44 UTC

README

Mail is a class to send mails using a SMTP server. It was derived from Zend\Mail, which is the reason it is published using the New BSD license rather than MIT, like the rest of Wedeto.

Features

  • Sending of messages using SMTP
  • Use SSL or TLS as encryption
  • Authenticate using PLAIN, LOGIN or CRAM-MD5
  • Send simple text messages, or compose complex message using Mime
  • A simple interface to create HTML e-mails with embedded images and attachments

Difference from Zend\Mime

Wedeto\Mail\Mime is derived from Zend\Mime. The functionality has been extended to make it easier to use. Wedeto\Mail\Mime\Message itself can now be added as a part to a Mime multipart message, to create nested Mime structures.

This in turn allows you to send messages containing attachments, embedded images and text / html alternatives.

Differences from Zend\Mail

Wedeto\Mail is derived from Zend\Mail. However, it has been changed in fundamental ways. Every dependency on other parts of the Zend framework was stripped out. Additionally, support for other transports and protocol was stripped out. The aim of Wedeto\Mail is to be lightweight and functional, not to be a building block to create webmail application. Therefore, support for IMAP and POP was removed.

Support for alternate transports such as Sendmail and PHP's mail function was removed as well. When Sendmail is available, a SMTP server is usually also available on localhost and is therefore superfluous. PHP's mail function should not be used at all, as it's highly inefficient and inflexible.

Wedeto\Mail does not support to create a Wedeto\Mail\Message from an existing mail message. Because all POP and IMAP support has been stripped this is no longer necessary. This allowed to strip down the complex header parsing situation and store the header in a simpler structure.

A new class was added, Wedeto\Mail\HTMLMessage. This eases the construction of messages containing a HTML part, a text part, attachments and embedded images, to create a structure like:

HTMLMessage

  • Message container (Wedeto\Mail\Mime\Message)
    • Plain text (Wedeto\Mail\Mime\Part)
    • HTML Container (Wedeto\Mail\Mime\Message)
      • HTML Message (Wedeto\Mail\Mime\Part)
      • Embedded image 2 (Wedeto\Mail\Mime\Attachment)
      • Embedded image 2 (Wedeto\Mail\Mime\Attachment)
  • Attachment 1 (Wedeto\Mail\Mime\Attachment)
  • Attachment 2 (Wedeto\Mail\Mime\Attachment)

Usage

There's one transport, Wedeto\Mail\SMTPMailer. It can be created without any argument, in which case it defaults to connecting to localhost on port 25. You can specify the following options:

  • hostname
  • port
  • username
  • password
  • ssl (SSL or TLS)
  • auth_type (PLAIN, LOGIN, CRAM-MD5)

Provide these options in an associative array:

use Wedeto\Mail\SMTPMailer;

$mailer = new SMTPMailer(array(
    'hostname' => 'localhost',
    ...
);

A HTML message can be composed with Wedeto\Mail\HTMLMessage:

use Wedeto\Mail\HTMLMessage;

$msg = new HTMLMessage;
$msg->setHTML('<html><head></head><body><h1>Hi there</h1><p>My message</p>');

You can add attachments and embed images:

$imgurl = $msg->embed('my_image.jpg');
$msg->setHTML('<html><head></head><body><h1>Hi there</h1><p>My message <img src="' . $imgurl . '" /></p>');
$msg->attach('my_document.pdf');

You can also generate the attachment or embedded image in memory and provide a stream:

$msg->attach('my_document.pdf', $my_resource);

The correct structure will be generated. When you set the HTML, the plain text is automatically generated by converting breaks and paragraphs to newlines and stripping all HTML. However, you may want to override this to provide your own text:

$msg->setPlain('Your mail client does not seem to render HTML. You can visit the online version here: http://your/website');

Once you are satisfied, you can use the transport to send the message.

$msg->addFrom('your@email.com', 'Your name');
$msg->addTo('their@email.com', 'Their name');
$msg->addBcc(['one@example.com', 'two@example.com']);

$mailer->send($msg);

That's it, it's sent!

Of course, you can also compile your own message using Wedeto\Mail\Message, building a message using Wedeto\Mail\Mime\Message and Wedeto\Mail\Mime\Part, much in the same way as you can with Zend\Mail and Zend\Mime.