Email

Elgg has the ability to send out emails. This can be done directly using functions like elgg_send_email() and notify_user() or indirectly through the notifications system. Below an overview of the feature of the email system.

HTML Mail

As an admin you can configure your site to have all outgoing emails to be HTML emails or just plain text emails. HTML emails are enabled by default. When enabled the email contents will be wrapped in HTML elements and some CSS will be applied. This allows theme developers to style the emails.

The appropriate views to format and style the emails can be found in views/default/email.

The CSS will be inlined automatically so it will work in most email clients. If your email contains images, those images can be converted to inline base64 encoded images (default) or attachments. Converted images are the best way to have images show consistently in various clients.

Instead of having the message converted automatically to a HTML, you can also provide your own html_message in the params of a notification. The html_message can be either a Elgg\Email\HtmlPart or a string. If it is a string Elgg will automatically try to inline provided CSS present in the css param. If you do not want to inline CSS you will need to set the convert_css param to false. Below an example of a custom HTML part.

elgg_send_email(\Elgg\Email::factory([
        'from' => 'from@elgg.org',
        'to' => 'to@elgg.org',
        'subject' => 'Test Email',
        'body' => 'Welcome to the site',
        'params' => [
                'html_message' => '
                        <p>Welcome to the site</p>
                        <img src="site_logo.png"/>
                ',
                'convert_css' => true,
                'css' => 'p { padding: 10px;}'
        ],
]));

Attachments

notify_user() or enqueued notifications support attachments for e-mail notifications if provided in $params. To add one or more attachments add a key attachments in $params which is an array of the attachments. An attachment should be in one of the following formats:

• An ElggFile which points to an existing file

• An array with the file contents

• An array with a filepath

// this example is for notify_user()
$params['attachments'] = [];

// Example of an ElggFile attachment
$file = new \ElggFile();
$file->owner_guid = <some owner_guid>;
$file->setFilename('<some filename>');

$params['attachments'][] = $file;

// Example of array with content
$params['attachments'][] = [
        'content' => 'The file content',
        'filename' => 'test_file.txt',
        'type' => 'text/plain',
];

// Example of array with filepath
// 'filename' can be provided, if not basename() of filepath will be used
// 'type' can be provided, if not will try a best guess
$params['attachments'][] = [
        'filepath' => '<path to a valid file>',
];

notify_user($to_guid, $from_guid, $subject, $body, $params);

E-mail address formatting

Elgg has a helper class to aid in getting formatted e-mail addresses: \Elgg\Email\Address.

// the constructor takes two variables
// first is the email address, this is REQUIRED
// second is the name, this is optional
$address = new \Elgg\Email\Address('example@elgg.org', 'Example');

// this will result in 'Example <example@elgg.org>'
echo $address->toString();

// to change the name use:
$address->setName('New Example');

// to change the e-mail address use:
$address->setEmail('example2@elgg.org');

There are some helper functions available

• \Elgg\Email\Address::fromString($string) Will return an \Elgg\Email\Address class with e-mail and name set, provided a formatted string (eg. Example <example@elgg.org>)

• \Elgg\Email\Address::fromEntity($entity) Will return an \Elgg\Email\Address class with e-mail and name set based on the entity

• \Elgg\Email\Address::getFormattedEmailAddress($email, $name) Will return a formatted string provided an e-mail address and optionaly a name