Setup Mail Core

Mail Core is an easier addon to setup for your app, but there is some more complicated setup to allow for testing in the Framework System.

Generic Setup

Of course, before any of the specific setup for the addon can be completed, you must do the generic setup for all addons to install it to the app. If you forgot how to do this, see Setup section of Using Addons in the main docs.

Specific Mail Core Setup

Per App Setup

There is only one thing you need to do in order to setup the app for mail core, but there are some other things that you are able to do in setup.

Required: Mail Core Sender Name

The only other thing needed to finish setting up Mail Core is the default sender name to be filled out in settings. Do this by going to the app-dir/apps/my-app/server/config/app.php file. Then set the mail-core.sender.name property to "App Name Notifications". For example, if your app was "Message Center" it would look like this:

return [
    // other settings already existing
    "mail-core" => [
        "sender" => [
            "name" => "Message Center Notifications"
        ]
    ]
];

This sets the default name of the sender to "Message Center Notifications" if it is not overridden by the individual email (using setConfigFrom). If this is not set, the global default for all apps is Informatics Notifications.

Email Template Directory

Technically, you are able to change mail-core.templateDirectory to be something other than the default /content/email-templates if so desired. This should be done on the app level and not on the server level. However, it is unclear why you would ever want to change this directory, as you cannot use multiple template directories, and every app that uses mail-core so far has always used /content/email-templates, but that option is available if you have a use case for it.

Per Domain Setup

There are several settings that CAN be setup per domain, and while they all can be overridden in the app.php, these should not be configured in the app.php unless you are otherwise directed to do so, as these things are designed to be able to differently configure the apps based on what domain they are in. All of these additional setups are optional.

Required: Email Config

In order to send emails properly you will need to setup your email config, which can be set in your mail-core.config setting. If this is completely unset, Mail Core will not work on your domain. There are two ways to configure this:

  • Without SMTP. To use no SMTP, you need to set the mail-core.config.useSMTP to false (which defaults to true), and set up your email username and password in another way. This is the method that should be followed for a developing environment, and we explain the whole process of how to set up Sendmail for your developing environment, here. Library.olivet.edu is currently setup without using SMTP to send emails (though they are not fully set up the Sendmail route but another way).
  • With SMTP. To set it up with SMTP, you will need to figure out the configuration to send emails via SMTP through your domain provider, but there are many settings that you will need to put in mail-core.config (though useSMTP need not be set, since it defaults to true). Apps.bennerlibrary.com is set up currently by using SMTP. In all likelihood, all of these will need to be set, so talk to your domain provider if you do not know what some of these things are:
    • host This config must be set in order to properly send emails. There is no default as every host will be different.
    • port This defaults to 25, but based on your domain email provider, this will likely change as well.
    • isEncrypted This defaults to true, and it will probably remain true.
    • smtpSecureType This defaults to tls, but another common SMTP secure type used by many domains is ssl.
    • username If username and password are set (which most likely they should be), Mail Core will automatically set SMTPAuth to true, but if it is not set, then it will not use SMTPAuth. Username has no default.
    • password If username is set, password should also be set, but obviously, password has no default.
//mail-core config if not using SMTP
'mail-core' => [
  'config' => [
      'useSMTP' => false
  ]
];

//mail-core redacted config if not using SMTP
'mail-core' => [
  'config' => [
      'host' => '*****',
      'port' => 465,
      'isEncrypted' => true,
      'username' => '*****',
      'password' => '*****',
      'smtpSecureType' => 'ssl'
  ]
];

There is one last optional override for mail-core.config, and that is that you can change the SMTPDebug level for PHPMailer by setting it directly in mail-core.config.smtp-debug or you can change it indirectly by setting mode (not mail-core.mode) in the settings. By default if you are in Development mode, then the SMTPDebug level will be 3, but if you are in any other mode, you will be at 0. Unless this is overridden by the configuration of mail-core.config.smtp-debug. For a total list of the meanings of the five different options for debug level (0-4), click here.

Sender

There are a few more optional things that you are able to set up in the mail-core.sender config that will change the sender information of any emails from this app. These should all be set up PER DOMAIN, so this should always be done in the local.php, not in app.php. You can change both the mail-core.sender.domain and the mail-core.sender.email of the sender that is used within your local.php settings file. This can be found for your individual app at the same location as your app.php, or the global local.php can be found at apps-dir/config/local.php. Here is what you need to know about each of them:

  • mail-core.sender.domain should probably never be changed. By default it uses HTTP_HOST of your server, and for SMTP protocols it is probably best that it stays this way, but it technically can be overridden with this setting. This will be the part of the email after the "@".
  • mail-core.sender.email can override the default email user. By default, it uses the app short code for the email user. This is how it is setup on apps.bennerlibrary.com (which is why the email is from Message Center is "msgc@bennerlibrary.com" on that domain). On the library.olivet.edu, it has been overridden using this property to "oss-lib" (which is why the email comes from "oss-lib@olivet.edu" on that domain).
  • mail-core.sender.email can also be set on the domain level. It will be overridden if a different name is set using setConfigFrom, or if it is overridden in the app.php of the specific app (as is described above), but if you want another fallback before "Informatics Notifications" which is the ordinary default, you can set that up on the domain level.