Sending email from mDIS

Emails should be sent to new users after registration, or when a user tries to reset the password, or uses the password reminder (available since v2.0.1). Therefore, configuring the mDIS for sending mail is sometimes required.

The web.php config file

In the backend/config directory you can find important information on how to enable mDIS to send emails.

See in particular the config/web.php configuration file (for mailer setup); and the config/params.php file for configuring the sender email address. Enter a valid email address of an mDIS admin there. (The default sender of the password-reset mail is an @example.com Address - in case you forget to set this up.)

Setting up the PHP mailer

An administrator must enable various options via config files.

Configure Mailer for common Outgoing Mail servers

Inside configuration file "backend/config/web.php", section components there is a configuration section mailer, determining how mails are sent by the webserver. Default setting for development is useFileTransport => true. This implies that mails are not actually sent, but saved in a temporary directory. They are stored inside "backend/runtime/mail" as .eml-files.
These .eml files should be purged occasionally.

To enable sending of email, set this in backend/config/web.php, section components:

   // modern settings, "Symfony Mailer" based;
   // for a modern Outgoing Mail server 
   // that supports encryption during login
    'mailer' => [
        'class' => '\yii\symfonymailer\Mailer',
        'transport' => [
            'scheme' => 'smtp',
            'host' => 'mail.gfz-potsdam.de',
            'username' => 'knb',
            'password' => '_top_secret_!_',
            'port' => 587,
            'encryption' => 'starttls',

        ],
        'useFileTransport' => false,
    ],
    
// Development setting - write to .eml files: (mDIS default)
    // Do NOT actually send emails
    // 'mailer' => [
    // class' => '\yii\symfonymailer\Mailer',        
    // send all mails to a file by default. You have to set
    // 'useFileTransport' to false and configure a transport
    // for the mailer to send real emails.
    //     'useFileTransport' => true,
    // ],

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

Configure Mailer for Google GMail

If you want to test sending mail with GMail, try this:

Install additional dependencies for GMail:

composer require symfony/google-mailer
composer require symfony/sendgrid-mailer

1
2

These 2 PHP packages install no other dependencies.
See Symfony Documentation (opens new window) for details.

Then, in backend/config/web.php, section components:

    'mailer' => [
        'class' => '\yii\symfonymailer\Mailer',
        'transport' => [
            'dsn' => 'gmail+smtp://knb......@gmail.com:16char_app_password@default'
        ],
        'useFileTransport' => false,
    ],

1
2
3
4
5
6
7

The dsn string means "data source name" and is just an alternative, more compact way of specifiying credentials for the mailer.

You also have to create a Google App Password for your GMail account. See Google Documentation (opens new window) for details.

Configure Legacy Mailer (deprecated)

Old mDIS versions used the "Swiftmailer" library. This is no longer supported.

// "Swiftmailer" Settings, no longer supported (deprecated) 
// since ~2020. do not use:
'mailer' => [
    'class' => 'yii\SymfonyMailer',
    'messageConfig' => [
        'charset' => 'UTF-8',
        'from' => 'knb@gfz-potsdam.de'
    ],
    'transport' => [
        'class' => 'Swift_SmtpTransport',
        'host' => 'smtp.gfz-potsdam.de',  // or e.g. smtp.gmail.com
        'username' => 'icdp',
        'password' => '',  // use master password
        'port' => '465',
        'encryption' => 'ssl',
    ],
],

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

See Yii-Swiftmailer Documentation (opens new window)

Configure Sender Email Address

To set the logging level and enable emails to be sent to you on Error, set this in backend/config/web.php, section components:

'log' => [
    'traceLevel' => YII_DEBUG ? 3 : 0,
    'targets' => [
        'all_messages' => [
            'class' => 'yii\log\FileTarget',
            'levels' => ['info', 'trace', 'warning', 'error']
        ],
        'problems' => [
            'class' => \yii\log\EmailTarget::className(),
            'levels' => \yii\log\Logger::LEVEL_ERROR,
            'message' => [
                'to' => 'knb@gfz-potsdam.de'
            ]
        ]
    ],
],

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

See Yii Logging Documentation (opens new window)

Enable/Disable Email Sending quickly

There is a setting available to mDIS admins with command line access:

./yii config/list

Output:

 - AppShortName = mdis-....
 - ...
 - CanSendEmails = 
 - ...

1
2
3
4

As you can see, the setting CanSendEmails is empty. This means that no emails are sent. You have to set it to a nonempty value, e.g. yes:

./yii config/set CanSendEmails yes
# disable with: 
./yii config/delete CanSendEmails
# reset to undefined value CanSendEmails =

1
2
3
4

mDIS on VirtualBox: emails

Concerning the mailer setup inside a VirtualBox instance: Sending mail from within a VirtualBox Guest should work.