Working with the Mail-Service
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:
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
$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:
We also can set a HTML-body manually by using
setHTMLbody() 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:
It is preferable though to create a template because it's cleaner coding.
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
If we set a pacakage handle as second parameter, it will take the template from the
Just set the name of the template file as string without extension (.php).
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.
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:
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.
Adding a sender is simple. The
from() method takes 2 parameters, email address and name:
$mailService->from('firstname.lastname@example.org', 'James Bond');
Also we can add a "Reply to" which works the same way as
$mailService->replyto('email@example.com', 'James Bond');
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('firstname.lastname@example.org,email@example.com,firstname.lastname@example.org', 'Name of the recipient (optional)');
bcc() work exactly the same way.
Now we have all together. Let's send our mail by calling:
These are just the most common methods of the Mail Service API. To see a full List of all possibilities, visit the API: