Mailboxes turn incoming emails into tickets automatically. This article covers all connection types, processing configuration, and the scheduler tasks that monitor response time, deadline compliance, and escalation.
Mailbox concept and usage types
In ZEP, a mailbox is a configured email account with stored credentials. Each mailbox can serve one of three uses:
Default mailbox: A central company mailbox. It is used when ZEP sends automatic emails and no other mailbox applies. Exactly one mailbox can be marked as the default mailbox.
Department default mailbox: With the Locations & Departments area, each department can have its own default mailbox. The assignment automatically applies to sub-departments. Without a match, ZEP falls back to the company-wide default mailbox.
Task mailbox: Each project task can have its own mailbox. Incoming mails to this address land directly as tickets in the correct task — the sender does not need to know the project or task.
Note: A mailbox can only serve one use at a time. A mailbox already assigned to a task cannot also be set as default or assigned to a department.
When ZEP sends an email from a ticket, it automatically sets the correct reply-to address. If the process has its own mailbox assigned, that address is used – replies from customers then land back in the correct mailbox and are processed as a ticket again. If no process mailbox is assigned, for example because a ticket was moved to a different process, the standard mailbox applies as described above.
Set up mailboxes
Mailboxes are managed under Administration > Ticket System > Mailboxes. Per mailbox you configure the connection type, credentials and processing options. To manage mailboxes, you need the Administration Area permission under Roles & Permissions, with Edit to create and change mailboxes. Administrators always have this permission.
Warning: ZEP downloads the emails of a ticket mailbox and deletes processed emails from the server. Therefore, never enter an employee's personal inbox as a mailbox, since their emails would then become tickets visible to all task team members.
POP3
Classic mail retrieval without folder support. ZEP fetches all mails and deletes them from the server after successful processing. Default port is 995 (SSL) or 110 (unencrypted). Without folders, ZEP always reads the inbox of the mailbox. If you want to separate ticket mail from the rest, you need a dedicated mailbox for it, or you switch to IMAP and name a folder there. Deleting after successful processing, by contrast, is not specific to POP3 but applies to every type of mailbox.
IMAP
IMAP additionally supports folders (dot-separated path, e.g. INBOX.Tickets). Default port is 993 (SSL/TLS) or 143 (STARTTLS or unencrypted).
Optionally activate the Microsoft OAuth checkbox to store an OAuth2 authentication per mailbox instead of username and password. You then enter OAuth ID, OAuth Secret and scopes (default scope: offline_access https://outlook.office.com/IMAP.AccessAsUser.All). The Microsoft Entra Admin Center must provide a corresponding app registration.
If the login to a mailbox with username and password fails, ZEP suspends the retrieval for 30 minutes and reports until when the mailbox will not be retrieved. This keeps a directory service from locking the account after several failed attempts. Mailboxes using Microsoft OAuth or the Microsoft Graph API are not affected, because they log in without a password. As soon as you correct the password and save the mailbox, ZEP retrieves again immediately. A successful login also ends the pause.
Microsoft Graph API
The most modern Microsoft 365 connection uses a single configured app access for all mailboxes of the instance. Instead of separate credentials per mailbox, you only register the mailbox address — authentication and token management are handled centrally by ZEP.
The Graph API credentials (Tenant ID, Client ID, Client Secret) are maintained via the Graph API Settings button in the mailbox overview. Required Microsoft permissions: Mail.Read and Mail.ReadWrite as application permissions. Server, port and encryption are set automatically and cannot be changed.
Note: We recommend setting up OAuth or Graph API together with ZEP support. The Microsoft configuration is instance-specific, and errors in the app registration lead to repeated authentication issues.
Configuration fields per mailbox
When creating or editing a mailbox, the following fields apply:
Short name: Unique identifier, max. 64 characters. Cannot be changed after saving.
Type: POP3, IMAP or Microsoft Graph API.
Server / Port / Encryption: Freely set for POP3 and IMAP. Automatic for Graph API.
Email (sender address): Used when ZEP replies via this mailbox.
Mailbox (username) and password: Mailbox credentials. With Graph API only the mailbox address is needed, no password.
Folder (optional, only IMAP/Graph): Path to the desired subfolder using dot notation, e.g. INBOX.Tickets.
Use secure authentication: Additional security option for classic IMAP/POP3.
Comment: Free text, internal.
Default mailbox: Checkbox to declare this mailbox the company-wide default (overwrites any previous default mailbox).
Inactive: Available when editing. An inactive mailbox is skipped by the scheduler task but remains stored — useful for temporary maintenance without data loss.
Warning: When a mailbox is assigned to a task, all existing emails in it will be converted into tickets at the next run and then deleted. Use an empty mailbox for task assignments.
Generate tickets from emails
Once a mailbox is set up as default, department default or task mailbox, the scheduler task Check mailboxes for tickets retrieves it at regular intervals. Default frequency every 15 minutes, alternatively every 5 minutes.
Processing logic per email
Per incoming mail, ZEP runs the following steps:
Filter check: If the subject filter matches (see below), the mail is skipped or optionally deleted.
Existing ticket lookup: ZEP uses the external ticket number or known ticket numbers in the subject to check whether the mail belongs to an existing ticket. On match, the mail is added as a new comment with attachments.
Subtask lookup: If no ticket match is found, ZEP searches for a matching subtask.
Create new ticket: If no match is found, ZEP only creates a new ticket if the mailbox is assigned to a task. The subject becomes the ticket subject (or "[no subject]" if empty), the mail body becomes the first comment, attachments are taken over.
Default mailbox: Emails to the default mailbox do not create new tickets. They can only update existing tickets or subtasks.
Remove mail from server: After successful processing the mail is deleted from the server (POP3 and IMAP via delete command, Graph API via REST call).
Regular-expression filter
Under Administration > Ticket System > Settings you enter a regular expression that ZEP applies to the subject of every email. If the subject matches, ZEP filters the email out and does not process it. ZEP processes all other emails as usual.
Example: The expression ^(Out of Office|Automatic reply) filters out automatic absence notices.
Also activate Delete the filtered-out messages from the mailbox so the mailbox does not fill up. Without this option, filtered-out emails stay in the mailbox.
External ticket-number detection
Per task mailbox you can store a regex that extracts an external ticket number from the mail subject. This is stored in the corresponding ticket field and allows reply emails to be matched to the right ticket — even if the subject varies.
Without a regex, ZEP falls back to simple string matching: if the subject already contains a known external ticket number, the mail is mapped to that ticket.
Attachments
Attachments of the incoming mail are stored as file attachments on the ticket. HTML mails are additionally attached as a standalone text.html file, the plain text becomes the first comment. Inline images (e.g. embedded graphics from mail signatures) are inlined into the HTML attachment as Base64 data strings so they display even offline.
Mail templates
The basic mail-template functions (subject, body, placeholders, multi-language maintenance and test send) are documented in the article Master data – Ticket System.
Notifications
The basic notification configuration (triggers, recipient groups, mail template per event and fallback recipients) is documented in the article Master data – Ticket System. For mailbox workflows, the events Ticket created (via email) and Remark / files added (via email) and the recipient Email Sender (for automatically created tickets) are intended. You maintain notifications for a single project in the project under Project Settings > Ticket Notifications.
Scheduler tasks in the background
Three scheduler tasks keep the mailbox and escalation workflow running. The tasks are configurable under Administration > System > Tasks and started by the ZEP scheduler:
Check mailboxes for tickets: Retrieves all active mailboxes and runs the processing logic. Default frequency every 15 minutes, alternatively 5 minutes. For Microsoft 365 OAuth accounts there is an automatic workaround: up to four attempts with 60-second pauses, since Office 365 can interrupt individual connections when multiple OAuth mailboxes are checked.
Ticket deadline compliance: Sends email reminders about open tickets whose deadline is approaching or already exceeded.
Ticket response time: Reports by email tickets that are still in status new a set number of days after arrival.
Ticket deadline compliance: Under Number of days to deadline you set how many days before the deadline ZEP sends a reminder about open tickets (status new or in process). The default is 2 days. Overdue tickets are included. With a negative value down to -10, ZEP reminds only once the deadline has been exceeded by that many days.
Ticket response time: Under Number of days since creation you set after how many days ZEP reports a ticket that is still in status new. The default is 7 days.
For both tasks you can optionally limit the reminder to individual priorities under Prio. The email goes to the project managers, if none are assigned to the department managers (with the Locations & Departments area) and finally to the administrators. Deadline compliance also informs the ticket processor.
Note: Each task is run independently by the scheduler. In case of problems, the run log is available under Administration > System > Tasks. Detailed error messages per mailbox appear directly in the task result.
Maintain and delete mailboxes
Via the edit dialog of a mailbox you can mark it as Inactive — the scheduler task skips inactive mailboxes without reading or deleting any mails. This pauses temporarily without data loss.
A mailbox can only be deleted if it is not assigned to a task or to a department as default mailbox. Resolve these assignments first in the respective detail views, or assign a different mailbox.
Common error sources
Incoming emails do not become tickets — typical causes:
Mailbox not assigned to any use: A mailbox that is only set up but not marked as default or assigned to a task is not retrieved by the scheduler task.
OAuth token expired: With classic OAuth (per mailbox), the token must be refreshed after Microsoft-side changes. The task result shows a hint "Please check whether the following mailboxes are logged into ZEP …".
Graph API permission lost: If the app registration in Microsoft Entra was changed or the client secret was rotated, retrieval fails. Update the Graph API credentials under Mailboxes > Graph API Settings.
Mailbox full: Some providers block mail retrieval on overflow. Activate the filter with the option Delete the filtered-out messages from the mailbox or maintain the mailbox manually.
Regex filter too restrictive: Check the global filter — it runs against the subject, not the body. On filter match, the mail is not processed.
Default mailbox creates no tickets: A mailbox only marked as default updates existing tickets only. New tickets are only created via task mailboxes.