Quick Links

Incoming Mail Server Settings

Configure your organization's mail server to receive and process incoming emails. You can use email protocols (POP, IMAP, POPS, or IMAPs), Exchange Web Services (EWS), or Microsoft Graph to connect ServiceDesk Plus with the mailbox.

Role Required: SDAdmin

Depending on the connection protocol selected, configurations vary.

Beginning with the year 2023, basic authentication will not be supported to connect to Microsoft 365 (formerly Office 365) mailboxes. Click here to know more.

Configure Incoming Mail Server Protocol
- Email Protocols
- Exchange Web Services
- Microsoft Graph
Configure Incoming Mail Server Settings
Move Error Emails to a Different Folder
- Resolve Error Emails
Edit Mail Server Settings
Check Mail Server Connectivity

Configure Incoming Mail Server Protocol

Configure Mail Server with Email Protocols

Choose the Connection Protocol as POP/IMAP/POPS/IMAPS.
Choose the Authentication Type. Use the pointers given below to configure the mail server based on the authentication type:

Field Name	Basic Authentication	OAuth Authentication
Server Name / IP Address	Provide the name or IP address of the mail server from where emails should be fetched.
Username	Enter the username to access the organization mailbox.
Password	Enter the password to access the organization mailbox.	-
Email Address	Enter the email address of the mailbox to fetch incoming emails as requests. You can also specify alias email addresses using a comma. The configured email addresses will not be populated in To/CC/BCC fields while replying to or forwarding emails from ServiceDesk Plus.
Protocol	Select the protocol to connect to the mailbox. POP/POPS - Post Office Protocol/Post Office Protocol securely downloads email to your computer and then deletes them from the server. IMAP/IMAPS - Internet Message Access Protocol/Internet Message Access Protocol securely syncs the computer with the server, giving you the opportunity to access the server from several devices. OAuth authentication supports IMAPS protocol only.
Port	Specify the port number as per the selected protocol.
Authorization Server Details (Client ID, Client Secret, Authorization URL, and Token URL)	-	Obtain Client ID, Client Secret, Authorization URL, and Token URL from the authorization server.
Scope	-	Define the accessibility of the obtained OAuth tokens in the mailbox. For IMAPS protocol, scope will be auto-populated for the following mailbox: Office365: https://outlook.office365.com/IMAP.AccessAsUser.All, offline_access Gmail: https://mail.google.com Know more about default values populated as scope.
Redirect URL	-	Configure Redirect URL in the authorization server to register the ServiceDesk Plus and obtain tokens. Ensure that the application is accessed using the same host as the redirect URL for OAuth configurations to work.

If you are using Office365 GCC High mailbox, ensure that the TLD (top-level domain) is .us in the hostname, connect URL, authorization URL, token URL, and scope.

After setting up the configuration, click Save.

For OAuth Authentication, provide your login credentials and submit your consent for the mentioned permissions. The login credential should be the same as the username configured in the Mail Server Settings. Ensure that you have not blocked pop-ups and redirects in your browser to view the user consent window.

Configure Mail Server with Exchange Web Services

Configure your organization's mail server to receive and process incoming emails via Exchange Web Services (EWS).

Choose the Connection Protocol as Exchange Web Services (EWS).
Choose the Authentication Type. Use the pointers given below to configure the mail server based on the authentication type:

Field Name	Basic Authentication	OAuth Authentication
Connect URL	Provide the EWS URL to connect to the server (For example, https://<host_name>/EWS/Exchange.asmx).
Email Address	Enter the email address of the mailbox to fetch incoming emails as requests. The configured email addresses will not be mentioned in To/CC/BCC fields while replying to or forwarding emails from ServiceDesk Plus.
Username	Enter the username to access the organization mailbox.
Password	Enter the password to the organization mailbox.	-
Authorization Server Details (Client ID, Client Secret, Authorization URL, and Token URL)	-	Obtain the Client ID, Client Secret, Authorization URL, and Token URL details from the Authorization server. Click here to learn more.
Scope	-	Define the accessibility of the obtained OAuth tokens in the mailbox. For Office365 mailbox, scope will be auto-populated: https://outlook.office365.com/EWS.AccessAsUser.All, offline_access Know more about default values populated as scope.
Redirect URL	-	Configure Redirect URL in the authorization server to register ServiceDesk Plus and obtain tokens. Ensure that the application is accessed using the same host as the redirect URL for OAuth configurations to work.

After setting up the configuration, click Save.

Configure Mail Server with Microsoft Graph

Choose the Connection Protocol as Microsoft Graph.
Microsoft Graph supports only OAuth authentication. Use the pointers given below to configure the mail server:

Field Name	Explanation
Graph Endpoint	The global graph endpoint will be pre-populated here. Modify the endpoint if your organization comes under a specific national cloud. Click here to view the list of graph endpoints corresponding to various national clouds.
Email Address	Enter the email address from where the emails must be fetched.
Authorization Server Details (Client ID, Client Secret, Authorization URL, and Token URL)	Obtain the Client ID, Client Secret, Authorization URL, and Token URL details from the authorization server. Microsoft Graph supports Azure as the authorization server. If the same mailbox is configured in both incoming and outgoing mail server settings, ensure the client ID is different to avoid issues due to mail throttling limitations. Learn more.



Scope	Define the accessibility of the obtained OAuth tokens in the mailbox. For Microsoft Graph protocol, scope will be auto-populated as: Mail.ReadWrite,offline_access Know more about default values populated as scope.
Redirect URL	Copy the URL to register ServiceDesk Plus and obtain tokens from the authorization server. Ensure the application is accessed using the same host as the redirect URL for OAuth configurations to work.

After setting up the configuration, click Save.

Configure Incoming Mail Server Settings

Fetch mails every - Enter the time interval(in minutes) to schedule the subsequent mail fetching processes.
Enable proxy server - Process incoming emails through a proxy server. You can configure the proxy server in the application beforehand as discussed here.
Enable Email Debug - Obtain debug prints of subsequent emails fetched in the application. Enable this option only if recommended by the support team.
Disable new request creation by email - Restrict request creation via incoming emails. You can allow requests to be created from specific email addresses and domains by entering them in the given textbox.
- You can allow requests creation from certain email addresses. For example, heather@zylker.com.
- You can also allow request creation from certain domains by entering an asterisk (*) followed by @domain name. For example, *@zylker.com.

If request creation is disabled, only the specified email addresses/domains are allowed to create new requests. However, conversations can be added via emails.

Click Save.

Moving Error Emails to a Different Folder

In some cases, emails with processing errors can stop the mail fetching process. ServiceDesk Plus enables you to move such error emails to a different folder, thereby ensuring seamless mail fetching process.

You can create a separate folder in the application mailbox and direct the error emails to be moved to this folder.

Enable the Move Messages to error folder and configure as explained below.

Name of the error folder	Provide the name of the folder you have created.
Stop mail fetching after [ ] mails	Stop mail fetching when the number of error emails moved to the folder reaches the specified count.
Total number of mails in error folder	This displays the number of emails moved to the configured error folder. This count will be reset when all error emails are resolved and moved to inbox.
Move mails to inbox	Move the emails back to the inbox after resolving the errors.
Notify by email when a mail is moved from inbox to error folder	Notify technicians each time an error email is received. Ensure Send e-mail when an application error occurs notification is enabled under notification rules.

This feature is not applicable for mail servers configured with the POP/POPS protocol.

In case of connectivity issues when processing emails, the ongoing mail fetching process will be skipped and emails will not be moved to the error folder.

Resolve Error Emails

When moving emails to the error folder, the details of each email and the exception will be saved as text files(.txt). These files will be encrypted as they might contain Personally Identifiable Information(PII) of the customer. Follow the steps given below to resolve the error emails.

Click Download next to Error Logs. The support files along with the error logs will be decrypted and downloaded in a zip file.
Send the files to support@servicedeskplus.com for analysis.
Once all emails in the error folder are resolved, click Move mails to inbox. The resolved emails will be further processed in the application based on your help desk workflow.

Edit Mail Server Settings

In build 13001 or earlier, stop the mail fetching process and make the necessary changes.

In build 13002 or above, administrators can edit the mail server settings as needed. If a mail fetching process is ongoing, the application will prompt to disable mail fetching temporarily. After saving the changes, enable the fetching process manually.

Check Mail Server Connectivity

Click Fetch a sample mail to test the incoming mail server connectivity.

If the settings are configured right and the connection is successful, the oldest email from your mailbox will be fetched, along with its properties. If not, an error message will be displayed on the screen.

To learn more about troubleshooting mail server errors, click here.

Other Configurations

Configure Notifications for Connectivity Issues

This configuration applies only to versions 11206 and above

When an issue occurs while processing emails, notifications will be triggered to the technicians configured for error notifications in Admin > Notification Rules. However, if the application fails to connect to the mailbox, the current mail fetching schedule will be skipped and the application will try to reconnect to the mailbox during the next schedule. With every schedule, this process will recur in a loop and no emails will be fetched until the application connects to the mailbox.

ServiceDesk Plus provides a default threshold value to track down the number of consecutive failures attempts to connect to the mailbox. When this threshold value is reached, SDAdmins and associated technicians can be notified via bell notifications and emails respectively.

The count of consecutive failure attempts will be reset after each notification.

To configure the threshold value,

Connect to the ServiceDesk Plus Database
Execute the following query to know the configuration

select * from mailconfig where category like 'FETCHING_MAILBOX_CONNECTIVITY'

The configuration is instance based and hence 2 rows for each instance.

The paramvalue of CONSECUTIVE_RETRY_THRESHOLD denotes the threshold value configured in the application.
The paramvalue of NOTIFICATION_ENABLED denotes whether the notifications are enabled/disabled.

The given screenshot displays the default configuration, where 5 is the default threshold value and the notifications enabled by default.

Use the following query to update the threshold value:

update mailconfig set paramvalue='X' where parameter like 'CONSECUTIVE_RETRY_THRESHOLD' and category like 'FETCHING_MAILBOX_CONNECTIVITY' and helpdeskid='<corresponding_helpdesk_id>'

Provide the required value in place of X.

Use the following query to disable the notification:

update mailconfig set paramvalue='false' where parameter like 'NOTIFICATION_ENABLED' and category like 'FETCHING_MAILBOX_CONNECTIVITY' and helpdeskid='<corresponding_helpdesk_id>'

Use the following query to enable the notification:

update mailconfig set paramvalue='true' where parameter like 'NOTIFICATION_ENABLED' and category like 'FETCHING_MAILBOX_CONNECTIVITY' and helpdeskid='<corresponding_helpdesk_id>'

Restart the service to implement the changes.

Notifications for Stripped Attachments (version 13009 and later)

ServiceDesk Plus validates the following entities in incoming email attachments and inline images:

File Name
Extensions
Content Type
Empty File
File Size

If there are any errors in these entities,

The attachment/inline image will be dropped.
The sender and the technicians configured for error notifications will be informed by email.
A system log entry will be added.

To resolve dropping attachments or inline images, contact ServiceDesk Plus support with screenshot of the system log entry and the notification email.

System log entry for dropped attachment/inline image

Email notification for dropped attachment/inline image

The notification configuration is portal-specific, and it can be disabled by using the following query:

update GlobalConfig set paramvalue='false' where category like 'EMAIL_PROCESSING' and parameter like 'sendAttachmentStrippedNotification' and HELPDESKID=<corresponding_helpdesk_id>;

The notification sent when inline images are dropped can be disabled using the following query:

update mailconfig set paramvalue='false' where category like 'EMAIL_PROCESSING' and parameter like 'SEND_INLINE_STRIPPED_NOTIFICATION' and HELPDESKID=<corresponding_helpdesk_id>;

The file size for validating inline images can be modified using the following query. The default inline image size is 3 MB. You can configure -1 as the file size to skip validation.

update mailconfig set paramvalue='enter-file-size' where parameter like 'INLINEIMAGE_MAX_SIZE'

Use the following query to skip the validation of inline images or attachments. This prevents images or attachments from being dropped due to validation.

update mailconfig set paramvalue='true' where parameter='SKIP_INLINE_VALIDATION';

Restart the application after executing the query.

Errors and Solutions

The following section explains various errors and corresponding solutions.

1. Error: Attachment file name is invalid

Reason: File name of the attachment contains invalid characters.

Solution: Rename the attachment file. Use letters, numbers, dots, hyphens, and underscores in file names.

2. Error: Attachment files contain invalid content type

Reason: Content type in the attachment does not match the file extension. For example, an image file with the file name 'Alter.txt' will be dropped.

Solution: Ensure that the attached files have matching file content and extension.

3. Error: Attachment files contain invalid extensions

Reason: ServiceDesk Plus enables you to allow/restrict certain file types in the application. If the email attachments include files of the restricted type, the attachments will be dropped.

Solution: Ensure that the file type is allowed under Admin > General Settings > Attachments Settings. In ESM setups, go to ESM Directory > General Settings > Attachment Settings.

4. Error: Attachment contains empty files

Reason: ServiceDesk Plus does not allow empty files as attachments.

Solution: Ensure that the attachment file is not empty. If the file is not empty, it could have been dropped due to Antivirus/Firewall configurations. Please check with your IT administrator to check on antivirus/firewall settings.

5. Error: Attachment size exceeds the configured limit

Reason: Files that exceed the configured size will be dropped.

Solution: Check and modify the Maximum attachment size (MB) under Admin > General Settings > Attachment Settings. In ESM setups, go to ESM Directory > General Settings > Attachment Settings.

Disable Conversation Addition

Users can disable the addition of emails as conversations based on email headers by executing the below query.

update mailconfig set paramvalue='false' where category like 'EMAIL_PROCESSING' and parameter like 'CHECK_IN_REPLY_TO_FOR_CONVERSATION' and helpdeskid = <helpdeskid>;

In the above query, replace the <helpdeskid> with the portal ID. To find the portal ID, run the query given below.

select id, displayname from helpdeskdetails;

After executing this query, all portal IDs are returned. Pick the portal ID where you need to run the update query and replace the <helpdeskid> in the update query with this portal ID. Restart the application for the updated query to take effect.

The addition of emails as conversations is disabled. After disabling, conversations will be added based on the request ID/entity ID in the email subject.