Mailer Factory

Overview

The Mailer Factory, located in ./modules/Mailer/MailerFactory.php, helps developers generate outbound mailers for the system account as well as individual user accounts. The Mailer Factory is a replacement for SugarPHPMailer which is now deprecated.

Mailers

There are two types of outbound mailers: System and User. The follow sections will outline how to use each.

System Mailer

The system outbound mailer can be set using the getSystemDefaultMailer method. This will set the mailer to use the system outbound email account. 

Example

$mailer = MailerFactory::getSystemDefaultMailer();

User Mailer

The user outbound mailer can be set using the getMailerForUser method. This will set the mailer to use the outbound email account for a specific user. 

Example

$user = BeanFactory::getBean("Users", 1);
$mailer = MailerFactory::getMailerForUser($user);

Populating the Mailer

Setting the Subject

To set the email subject, use the setSubject method. It accepts a plain text string.

Example

$mailer->setSubject("Test Mail Subject");

Setting the Body

Depending on your email type, you can use the setTextBody and/or setHtmlBody methods respectively to populate the content of the email body.

Example

// Text Body
$mailer->setTextBody("This is a text body message");

// HTML Body
$mailer->setHtmlBody("This is an <b>HTML</b> body message. <br> You can use html tags.");

Note: The email HTML body is not necessary if you have populated the text body.

Adding Recipients

To add recipients to your email, you can use the addRecipientsTo, addRecipientsCc, or addRecipientsBcc methods . These methods require an EmailIdentity object as a parameter.

Example

$mailer->addRecipientsTo(new EmailIdentity('user1@yourcompany.crm', 'User 1'));
$mailer->addRecipientsCc(new EmailIdentity('user2@yourcompany.crm', 'User 2'));
$mailer->addRecipientsBcc(new EmailIdentity('user3@yourcompany.crm', 'User 3'));

Clearing Recipients

You can clear the current recipients specified in the mailer by using the clearRecipients method.

Example

$to = true; 
$cc = true; 
$bcc = true;

$mailer->clearRecipients($to, $cc, $bcc);

Adding Attachments

To add attachments, use the addAttachment method.

Example

$path = "/path/to/your/document";
$mailer->addAttachment(new Attachment($path));

Sending Emails

Once your email is populated, you can send it using the send method. The send method will return the content of the mail. If the Mailer Factory experiences an error, it will throw an exception. It is highly recommended to use a try and catch when sending emails.

Example

$mailSubject = "Test Mail Subject";
$mailHTML = "<h1>SugarCRM</h1><br> Test body message";
$mailTo = array(
    0 => array(
        'name' => 'Test User',
        'email' => 'test@yourcompany.crm',
    ),
    1 => array(
        'name' => 'Other Recipient',
        'email' => 'email@addres'
    )
);

$mailAttachment = "/path/to/pdf/files/document.pdf";

try {
    $mailer = MailerFactory::getSystemDefaultMailer();
    $mailTransmissionProtocol = $mailer->getMailTransmissionProtocol();
    $mailer->setSubject($mailSubject);
    $body = trim($mailHTML);
    $textOnly = EmailFormatter::isTextOnly($body);
    if ($textOnly) {
        $mailer->setTextBody($body);
    } else {
        $textBody = strip_tags(br2nl($body)); // need to create the plain-text part
        $mailer->setTextBody($textBody);
        $mailer->setHtmlBody($body);
    }
    $mailer->clearRecipients();
    foreach ($mailTo as $mailTo) {
        $mailer->addRecipientsTo(new \EmailIdentity($mailTo['email'], $mailTo['name']));
    }
    $mailer->addAttachment(new \Attachment($mailAttachment));
    $result = $mailer->send();
    if ($result) {
        // $result will be the body of the sent email
    } else {
        // an exception will have been thrown
    }
} catch (MailerException $me) {
    $message = $me->getMessage();
    switch ($me->getCode()) {
        case \MailerException::FailedToConnectToRemoteServer:
            $GLOBALS["log"]->fatal("BeanUpdatesMailer :: error sending email, system smtp server is not set");
            break;
        default:
            $GLOBALS["log"]->fatal("BeanUpdatesMailer :: error sending e-mail (method: {$mailTransmissionProtocol}), (error: {$message})");
            break;
    }
}