E-mail distribution

1. Introduction

The APF offers a custom API to send e-mails. The object oriented interfaces eases sending e-mails compared to native PHP function mail() and allows writing clearly structured code around sending e-mails.

The API consists of two components:

  • Message: Represents an e-mail message including all attributes such as sender, recipient, content type and content..
  • MailAddress: Represents a sender as well as well as a recipient.

Both classes allow e-mail distribution in compliance with RFC2822 and support all message options described in RFC5321.

2. Distribution

Sending a simple text e-mail can be accomplished with Message and MailAddress as follows:

PHP code
$sender = new MailAddress('Sender name', 'sender@example.com'); $subject = 'Subject'; $content = 'Content of the message'; $message = new Message($sender, $subject, $content); $message->addRecipient(new MailAddress('Empfänger-Name', 'recipient@example.com')); $message->send();

Creating a message, sender, subject, and content of the message are rquired. Recipients and others can be added as needed afterwards.

3. Further use cases

The following chapters contain further examples on configuration and distribution options using the APF e-mail API.

3.1. Definition of recipients

Class Message supports three types pf recipients: direct recipients (TO), copy recipients (CC) and blind copy recipients (BCC). The following code block describes how to add all three types to an e-mail:

PHP code
$message->addRecipient(new MailAddress('Recipient name', 'recipient@example.com')); $message->addCopyRecipient(new MailAddress('Recipient name', 'recipient@example.com')); $message->addBlindCopyRecipient(new MailAddress('Recipient name', 'recipient@example.com'));

To add multiple recipients at once, you may want to use the following code:

PHP code
$recipients = [ new MailAddress('recipient one', 'recipient.one@example.com'), new MailAddress('recipient two', 'recipient.two@example.com') ]; $message->setRecipients($recipients); $message->setCopyRecipients($recipients); $message->setBlindCopyRecipients($recipients);

To retrieve the current list of recipients you can use the following functions:

PHP code
$recipients = $message->getRecipients(); $copyRecipients = $message->getCopyRecipients(); $blindCopyRecipients = $message->getBlindCopyRecipients();

In case you intend to delete the current list of recipients - e.g. to send a message to multiple, independent recipients or groups - you may want to use the follwing code snippet:

PHP code
$message = new Message(...); // Send to group 1 $message->addRecipient(new MailAddress('...', 'recipient.one@e-mail.de')); $message->send(); $message->clearRecipients() ->clearCopyRecipients() ->clearBlindCopyRecipients(); // Send to group 2 $message->send(); $message->addRecipient(new MailAddress('...', 'recipient.two@e-mail.de')); $message->clearRecipients() ->clearCopyRecipients() ->clearBlindCopyRecipients(); ...

In case you want to get a notification from the responsible mail server in case of any issue, you can define a Return Path:

PHP code
$message->setReturnPath(new MailAddress('return postbox', 'return@example.com'));

3.2. Priority definition

The priority of any given e-mail can be defined as follows:

PHP code
$message->setPriority(Message::PRIORITY_HIGH); $message->setPriority(Message::PRIORITY_NORMAL); $message->setPriority(Message::PRIORITY_LOW);

3.3. MIME type definition

The MIME type - or the content type respectively - is defined as plain/text; charset=UTF-8 by default. The character set used is pre-filled from Registry entry Charset within namespace APF\core. Details on the basic framework configuration can be found under Basics.

In case you want to change the content type of the present e-mail instance please use method setContentType():

PHP code
$message->setContentType('text/html; charset=ISO-8859-1');

3.4. Pre-configured messages

To ease migration to the new e-mail API introduced in release 3.3 the APF includes the MessageBuilder. This component has been built to use a configuration file created for the mailSender (removed in version 3.3) to create a pre-configured e-mail message.

The configuration file typically includes the following attributes (excerpt from the Contact form module):

APF configuration
[ContactForm] Mail.SenderName = "..." Mail.SenderEMail = "..." Mail.ReturnPath = "..." Mail.ContentType = "text/plain; charset=utf-8"

The configuration contains sender, return path, and content type of the e-mail. Using the MessageBuilder, those values are directly injected into the Message instance.

The following examples shows how to create a message (Message) using configuration DEFAULT_mailsender.ini from namespace APF\tools\mail:

PHP code
$builder = $this->getServiceObject(MessageBuilder::class); $message = $builder->createMessage('ContactForm', $subject, $content);

The first argument of method createMessage() refers to the configuration section to be used to configure the message. In case you want to send several types of messages, simply define as many sections as needed and apply the name of the section with each call of this method.

Details on how to define configuration files can be taken from Configuration.


Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.
There are no comments belonging to this article.