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 module, 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.
Set up mailboxes
Mailboxes are managed under Administration > Ticketing System > Mailboxes. Per mailbox you configure the connection type, credentials and processing options. Only administrators have access to mailbox management.
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).
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.
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 > Ticketing System > Settings you can activate a global regex filter that runs against the subject. Example: only emails with prefix [Support] become tickets, all others are ignored.
Optionally activate Delete filtered messages so the mailbox does not fill up. By default, filtered messages remain 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
Under Administration > Ticketing System > Mail Templates you store the standard texts for automatic notifications. Each template has a subject and a body, both supporting placeholders (e.g. %NUMMER%, %BETREFF%, %BEARBEITER%) replaced on send.
Per template you can store separate texts per language (German, English, others) — the language of the addressed recipient is used. Via the action Test send you can mail a template to your own address to check formatting and placeholder resolution.
Notifications
Under Administration > Ticketing System > Notifications you define which event notifies which recipient group via email.
Trigger: new ticket, status change, comment added, processor changed, deadline missed.
Recipients: creator, processor, project manager, customer contact person — per trigger. Additional free-text email addresses.
Mail template: One template per trigger (see above).
Project-specific override: Per project you can set recipients or templates that deviate from the global configuration.
Escalation chain
If a ticket does not get a response or progression within the configured period, ZEP escalates to the next stage. The escalation chain typically runs through the following user groups:
Task processors
Task leads
Project members
Project managers
Department managers (with Locations & Departments module)
Administrators
At each stage, ZEP sends an escalation email to the corresponding group. The period until the next stage is defined per escalation task in the basic settings.
Scheduler tasks in the background
Four 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 escalation: Escalates open tickets when no response happens within the configured period. Default run: daily at 04:00.
Ticket deadline compliance: Sends warnings before and after the ticket deadline to processor and project manager. Configurable per number of days before and after the deadline.
Ticket response time: Measures the time between ticket arrival and first processing step. On deadline breach, defined recipients are informed.
Configuration of the deadline and response-time tasks: Per task you define the number of days before and after the deadline (positive number = after deadline, negative number = before, 0 = on the deadline itself). Additionally, a priority filter sets from which priority the reminder applies, and the escalation stage defines whether assignee, project management, department management or administrators are notified.
Note: Each task is run independently by the scheduler. In case of problems, the run log is available under Administration > System > Background 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 "Delete filtered messages" 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.