Email

Edit

Improvements?

Let us know by posting here.

The Mail Object

Create a mail object:

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

Set testing mode (throws an exception on error and disables logging when true):

$mailService->setTesting(false); // or true

Get testing setting:

$mailService->getTesting();

The Template

Create a mail template in /application/mail/ or /packages/package_handle/mail. Example:

<?php
$bodyHTML .= '<!DOCTYPE html>';
$bodyHTML .= '<html lang="de">';
// ...
$bodyHTML .= $mailContent;
// ...

Use $bodyHTML for HTML body. Copy and modify a template from /concrete/mail. $bodyHTML and $mailContent are key variables.

Set a body or HTML body manually:

$mailService->setBody("Dear Concrete team\n...");
$mailService->setBodyHTML("<p>Dear Concrete team<br>...</p>");

Get body or HTML body:

$mailService->getBody();
$mailService->getBodyHTML();

Using a template is preferred for cleaner coding.

Load a template with load():

$mailService->load('mail_template');
// or with package handle
$mailService->load('mail_template', 'package_handle');

Add parameters to the template with addParameter():

$mailContent = '<p>Dear Concrete team<br>...';
$mailService->addParameter('mailContent', $mailContent);

The Subject

Set subject in the template with setSubject():

$subject = 'A great CMS'; // In template
$mailService->setSubject('A great CMS'); // Using method

Get the subject:

$mailService->getSubject();

Attachments

Add attachments using a File object:

$attachment = \Concrete\Core\File\File::getByID(123);
$mailService->addAttachment($attachment);

The Sender

Set sender and "Reply to":

$mailService->from('email@example.com', 'Name');
$mailService->replyto('email@example.com', 'Name');

Adding Recipients

Add recipients with to(), cc(), and bcc():

$mailService->to('user@domain.com', 'Name');

Sending

Send the mail:

$mailService->sendMail();

API

For more methods, see the Mail Service API:

API Reference

Configure Email Sender Addresses

Concrete CMS allows customizing sender addresses for internal emails. These are grouped for ease of configuration:

  • Group A: Uses a global default sender address
  • Group B: Allows individual sender address settings per message
  • Group C: Configurable sender address through the admin UI

Settings are managed in concrete.php in the application/config directory. Do not edit the file in generated_overrides.

Group A: Global Default Sender

These emails share a common sender address:

  • Private message notifications
  • Conversations new message notifications
  • New badge notifications

Settings:

  • Address: concrete.email.default.address
  • Name: concrete.email.default.name (optional)

Example in concrete.php:

return array(
    'email' => array(
        'default' => array(
            'address' => 'your@email.com',
            'name' => 'Your Site', // Optional
        ),
    ),
);

Default fallback address uses the default system address for the site, which by default is the superadmin user's email address.

Group B: Individual Sender Addresses

Allows unique sender addresses:

  • Form block submit notifications
  • User registration email validation
  • Forgot password email

Settings:

  • Form block: concrete.email.form_block.address
  • Registration validation:
    • Address: concrete.email.validate_registration.address
    • Name: concrete.email.validate_registration.name (optional)
  • Forgot password: concrete.email.forgot_password.address

Example in concrete.php:

return array(
    'email' => array(
        'form_block' => array(
            'address' => 'your@email.com',
        ),
        'validate_registration' => array(
            'address' => 'your@email.com',
            'name' => 'Site Email Validation', // Optional
        ),
        'forgot_password' => array(
            'address' => 'your@email.com',
        ),
    ),
);

Default sender: System's super user email. Not affected by global sender address.

Group C: Admin UI Defined Sender

User registration notifications' sender address is set in the admin UI under System & Settings > Login & Registration > Public Registration.

Complete Example

return array(
    'email' => array(
        'default' => array(
            'address' => 'your@email.com',
            'name' => 'Your Site', // Optional
        ),
        'form_block' => array(
            'address' => 'your@email.com',
        ),
        'validate_registration' => array(
            'address' => 'your@email.com',
            'name' => 'Site Email Validation', // Optional
        ),
        'forgot_password' => array(
            'address' => 'your@email.com',
        ),
    ),
);