Working with the Mail-Service

Edit

Improvements?

Let us know by posting here.

The Mail Object

First we create a mail object:

$mailService = Core::make('mail');

Next we decide, if we want Concrete CMS to throw an exception if something went wrong while sending the mail. Also when set to true Logging is disabled:

$mailService->setTesting(false); // or true to throw an exception on error.

The get the Testing setting we use:

$mailService->getTesting();

The Template

You may send mails by creating just a body on the fly or by loading a template first. Let's have a look at the template. To create a template simply create a new PHP file inside the /application/mail/ folder or if in a package /packages/package_handle/mail. This file must look similar to this:

<?php
$bodyHTML .= '<!DOCTYPE html>';
$bodyHTML .= '<html lang="de">';
$bodyHTML .= '  <head>';
$bodyHTML .= '      <meta charset="utf-8">';
$bodyHTML .= '  </head>';
$bodyHTML .= '  <body>';
$bodyHTML .= '      <div>';
$bodyHTML .= $mailContent;
$bodyHTML .= '      </div>';
$bodyHTML .= '  </body>';
$bodyHTML .= '</html>';

The important thing is that we call the $bodyHTML exactly like this to be recognised as HTML-Body.

We may also copy a template from /concrete/mail and adapt it to our needs. The important parts here are the variables $bodyHTML and $mailContent. When loading the template into our Mail object, the body will be loaded automatically into it. We may set parameters ($mailContent) to be loaded into our template like in any other view (see below).

We can set a body or an HTML-body manually by using setBody(). These two methods takes one parameter, a string or a boolean set to false = not use plain text body:

$mailService->setBody("Dear Concrete team\nYour CMS is by far the best I\'ve ever seen.");

To get the body:

$mailService->getBody();

We also can set a HTML-body manually by using setBodyHTML() the same way:

$mailService->setBodyHTML("<p>Dear Concrete team<br>Your CMS is by far the best I've ever seen.</p>");

To get the HTML-body:

$mailService->getBodyHTML();

It is preferable though to create a template because it's cleaner coding.

The load()method attaches a mail template from the /mail/ directory to our mail object. It first looks for mail templates in /application/mail. If there's no template it will take the template from /concrete/mail. If we set a pacakage handle as second parameter, it will take the template from the /packages/package_handle/mail folder. Just set the name of the template file as string without extension (.php).

$mailService->load('mail_template');

or

$mailService->load('mail_template', 'package_handle');

Before loading the template we may add parameters to our template as said before. This works the same way as loading parameters from a page controller into a page view:

$mailContent = '<p>Dear Concrete team<br>';
$mailContent .= 'Your CMS is by far the best I\'ve ever seen.</p>';
$mailContent .= '<p>Thank you very much for your great efforts</p>';
$mailContent .= '<p>Best regards</p>';

$mailService->addParameter('mailContent', $mailContent);

The first parameter of addParameter() 'mailContent' will be the variable named $mailContent inside the template. Naturally we may add multiple parameters by invoking addParameter() several times. Don't forget to set all parameter variables set here inside the template too. Also we can send any type of data (arrays, objects, etc) and work with it inside the template as the template file is a normal PHP-file.

The Subject

Next we set a subject. There are 2 ways of doing this. The first is to set a variable called $subject inside the template:

<?php
$subject = 'A great CMS';
$bodyHTML .= '<!DOCTYPE html>';
// ...

The second option is to use setSubject() on our mail object:

$mailService->setSubject('A great CMS');

To get the subject:

$mailService->getSubject();

Attachments

Adding attachments to our mail is very easy too. We need a File object to do so:

$attachment = \Concrete\Core\File\File::getByID(123);

$mailService->addAttachment($attachment);

Naturally we may add multiple attachments by invoking addAttachment() several times.

The Sender

Adding a sender is simple. The from() method takes 2 parameters, email address and name:

$mailService->from('james.bond@mi6.com', 'James Bond');

Also we can add a "Reply to" which works the same way as from():

$mailService->replyto('james.bond@mi6.com', 'James Bond');

Adding recipients

Now we have to add a recipient to our mail. The to() method also takes 2 parameters. email address and name. The differnece here is that we can add multiple recipients in just one call of to() by separating the addresses by a coma:

$mailService->to('user@domain.com,another.user@another-domain.com,the.third@foobar.com', 'Name of the recipient (optional)');

The methods cc()and bcc() work exactly the same way.

Sending

Now we have all together. Let's send our mail by calling:

$mailService->sendMail();

API

These are just the most common methods of the Mail Service API. To see a full List of all possibilities, visit the API:

API Reference