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:
Sending a simple text e-mail can be accomplished with Message and MailAddress as follows:
$sender = new MailAddress('Sender name', 'email@example.com'); $subject = 'Subject'; $content = 'Content of the message'; $message = new Message($sender, $subject, $content); $message->addRecipient(new MailAddress('Empfänger-Name', 'firstname.lastname@example.org')); $message->send();
Creating a message, sender, subject, and content of the message are rquired. Recipients and others can be added as needed afterwards.
The following chapters contain further examples on configuration and distribution options using the APF e-mail API.
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:
$message->addRecipient(new MailAddress('Recipient name', 'email@example.com')); $message->addCopyRecipient(new MailAddress('Recipient name', 'firstname.lastname@example.org')); $message->addBlindCopyRecipient(new MailAddress('Recipient name', 'email@example.com'));
To add multiple recipients at once, you may want to use the following code:
$recipients = [ new MailAddress('recipient one', 'firstname.lastname@example.org'), new MailAddress('recipient two', 'email@example.com') ]; $message->setRecipients($recipients); $message->setCopyRecipients($recipients); $message->setBlindCopyRecipients($recipients);
To retrieve the current list of recipients you can use the following functions:
$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:
$message = new Message(...); // Send to group 1 $message->addRecipient(new MailAddress('...', 'firstname.lastname@example.org')); $message->send(); $message->clearRecipients() ->clearCopyRecipients() ->clearBlindCopyRecipients(); // Send to group 2 $message->send(); $message->addRecipient(new MailAddress('...', 'email@example.com')); $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:
$message->setReturnPath(new MailAddress('return postbox', 'firstname.lastname@example.org'));
The priority of any given e-mail can be defined as follows:
$message->setPriority(Message::PRIORITY_HIGH); $message->setPriority(Message::PRIORITY_NORMAL); $message->setPriority(Message::PRIORITY_LOW);
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():
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):
[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:
$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.