Configuring Email

Email Accounts

Email account types may be configured from the Tenant emails or from the Master Account. The tenant Emails are configured from inside the PCR-360. The master account is configured in the pcr360.ini file. See PCR-360#Configuration for more information about the INI file.

Transport Types

PCR-360 supports several email protocols. The Protocol used for your emails will depend on your needs and what is supported by your email service provider.

Type	Incoming Emails	Outgoing Emails	Tenant Email Configurable	INI Configurable
File	No	Yes	Yes	Yes
Sendmail	No	Yes	Yes	Yes
SMTP	No	Yes	Yes	Yes
IMAP	Yes	No	Yes	Yes
POP3	Yes	No	Yes	Yes
Office365	Yes	Yes	Yes	No
GMail API (2024.1.1+)	Yes	Yes	Yes	No

FILE

This configuration type creates an EML file in the email directory of the installation.
These files are not handled any further by the application.
This is usually only used on a test server.
Email Files will always be created when the type is in use

SENDMAIL

Outgoing protocol to send emails directly from the web server
If there is a problem delivering the email, info is added to the error log.

SMTP

Simple Mail Transfer Protocol is an outgoing email protocol that supports sending using a third-party email server
This configuration connects to an external SMTP server to send outbound emails
If there is a problem delivering the email, info is added to the error log.

POP3

Post Office Protocol 3 is an incoming email protocol that supports receiving emails using a third-party email server
This configuration connects to an external POP3 server to receive incoming emails
It utilizes the System Check Email Event to receive email message and convert them into Inquiries
The event will receive mail from all Service Desk Email Tenant incoming hosts AND any Master (INI) Incoming Host
If there is a problem receiving the email, info is added to the error log.

IMAP

Internet Message Access Protocol is an incoming email protocol that supports receiving emails using a third-party email server
This configuration connects to an external IMAP server to receive incoming emails
It utilizes the System Check Email Event to receive email message and convert them into Inquiries
The event will receive mail from all Service Desk Email Tenant incoming hosts AND any Master (INI) Incoming Host
If there is a problem receiving the email, info is added to the error log.

Office365 API (Version 2020.4+)

Click here for detailed Configuration Instructions: Configuring the MS Office 365 API
The Office365 Email API only supports Tenant Email configuration.
This type cannot be configured from the INI but will override the INI if set as the Default type Email Tenant
This configuration connects to Office365 OAuth2 API server to send and receive emails
It utilizes the System Check Email Event to receive email message and convert them into Inquiries
The event will receive mail from all Service Desk Email Tenant incoming hosts
The send address will be overridden by the default tenant email if it exists.
If there is a problem receiving the email, info is added to the error log.

Notes on O365 Authentication

PCR-360/Office 365 authentication requires signing into the mailbox the User wants to send/receive email from.

PCR-360 does not currently support the delegation of mailboxes in Office 365. So users cannot send an email as another mailbox from PCR-360.

If a User is logged into an SSO linked to MS Office Online and then attempts to authenticate an email account in PCR-360, it will use the logged in User to authenticate and start sending emails from that User.

To avoid this, these steps must be followed in the EXACT order.

Login to the PCR-360 Application (For Organizations using a Single Sign On (SSO) linked to MS Office online, this will also sign them into MS Office Online).
Log out of MS Office Online (only after completing step one)
Re-authenticate the email.
The User will be prompted to enter credentials and should enter the credentials for the mailbox in which they wish to send and receive email to and from. Again, not their personal email, but the mailbox that should appear as the sender on the emails from PCR-360.

GmaiL API (2024.1.1+)

Requires am authenticated Personal account or a service account capable of impersonating users.

See Configuring the Gmail API for more information

Configuration Types

The two types of email setup are the Master Default and the Tenant Emails. The Master Default is used as a fallback or a default for all email addresses.

Expected Behavior

"Master" INI email settings
1. An incoming "master" email should allow receiving new emails and converting them to SD Requests
2. An outgoing "master" should allow for sending all emails except SD threads
A "Default" Tenant Email
1. Should override the INI "master" settings when both exist
2. Should allow for sending all emails except SD threads
3. Does not receive emails
A "Service Desk" Tenant email should allow
1. Receiving new emails and converting them to SD Requests
2. Sending emails from SD Threads
3. SD Thread Emails are not sent unless an Email Tenant is setup with the type "Service Desk"
When constants.SEND_EMAIL is false, no emails should be sent or received for the environment

INI Configuration

Email may be completely disabled (sending and receiving) by setting the DISABLE_EMAIL constant to true.
The email form fields may be hidden and all email redirected to in app messages by setting SEND_EMAIL to false
SEND_EMAIL is true by default
DISABLE_EMAIL is false by default
The constants can be set for each individual environment in the INI file usually located at /var/www/pcr360/configs/pcr360.ini

Master INI

The master account allows specifying a single account for the entire application. Master Default Email Account is used for sending all non Service Desk emails if there is not a Tenant Default account entered; and also, for All Service Desk emails if there is neither a Tenant Service Desk email nor Tenant Default specified. It is setup by entering the login information to the PCR-360.ini file. See PCR-360#Configuration for more information about the INI file.

TENANTS_RECID - Specifies the tenant to use for emails (this is almost always 0)

ACCOUNT_TYPE - The account type is almost always master

EMAIL - The email address to use to send and receive emails

DISPLAY_NAME - The name that will be used on the email address: DISPLAY_NAME <email@server.com>

LOGIN - The username/login used for to connect to the third-party email server

PASSWORD - The password used for to connect to the third-party email server

OUTGOING_TRANSPORT_TYPE - The protocol used for sending emails

OUTGOING_HOST - Used for SMTP transport types. The email server mail used to send the emails

OUTGOING_PORT - The port used for outgoing server connections

OUTGOING_SSL - This value is set if the outgoing mail server supports SSL

INCOMING_MAILBOX_TYPE - The protocol used for sending emails

INCOMING_HOST - The email server mail used to receive the emails

INCOMING_PORT - The port used for incoming server connections

INCOMING_SSL - This value is set if the incoming mail server supports SSL

Example Configuration

CODE

email.TENANTS_RECID = 0
email.ACCOUNT_TYPE = "master"
email.EMAIL = "testtest@pcr.com"
email.DISPLAY_NAME = "PCR-360 Master (team360)"
email.LOGIN = 'testtest@pcr.com'
email.PASSWORD = 'testPassword23455'
email.OUTGOING_TRANSPORT_TYPE = "SMTP"
email.OUTGOING_HOST = "mail.pcr.com"
email.OUTGOING_PORT = 465
email.OUTGOING_SSL = "SSL"
email.INCOMING_MAILBOX_TYPE = "IMAP"
email.INCOMING_HOST = "mail.pcr.com"
email.INCOMING_PORT = 993
email.INCOMING_SSL = "SSL"

Tenant Emails

Adding a new Tenant Email

Tenant Emails are configured directly on the Tenant in the PCR-360 Application. This is accessed via Tenant Management from the Admin menu:

From here double click the Tenant to open the Tenant Form and open the Email Accounts Tab

Click the Add button to add a new Email Tenant, then fill in the appropriate fields:

Account Types:

Default - Each tenant may contain one Default account. Tenant Default Email Account is used for sending all non Service Desk emails and all Service Desk emails if there is no Tenant Service Desk email specified. The Default Account never receives email so the incoming settings are not available.

Service Desk - Service Desk Email Account is used to for sending and receiving all Service Desk emails. If there is not a Service Desk account specified then service desk emails will be sent with the Tenant Default Account (or the Master Default Account) but, service desk email will not be received.

More information on the account types and each parameter is available here: Email Account Parameters

Incoming Mail Event

In order to receive emails, PCR-360 needs to have an event setup to periodically check for new emails. This is configured on the Events screen by PCR.

Event Configuration

Add A New Event

Event: System Check Email
Frequency: 15 minutes
Listener: PCR_Utility_EmailManager
Listener Method: eventCheckMail
Data: The data needs a host set, this should be the URL of the virtual host that will be receiving the emails.
CODE
```
{
    "host":"pcr360.<customerDomain>.edu"
}
```
Save the event and if there is an incoming account set up in the Tenants Emails, it should now be checked every 15 minutes.

Outgoing Mail

SELinux

When SELinux is enabled on a machine, Apache must specifically be allowed to send mail. This is done with the following commands:

CODE

sudo setsebool -P httpd_can_sendmail 1
sudo setsebool -P httpd_can_network_connect 1

Firewall

If using Office365 SMTP, a non-standard port is used, 587 this needs to be opened in the Firewall.

Encrypting a Password

PCR-360's CLI can be used to encrypt email passwords

CODE

// Example is for a standard installation of a production environment and may need to be adjusted for non-standard or customer installs.
php /var/www/pcr360/prod/cli/zfcli.php -a cron.db.encrypt-password -e prod -i /var/www/pcr360/configs/pcr360.ini --js '{\"encrypt\":\"SET_PASSWORD_HERE\"}'"