Mail import in TOPdesk: preventing duplicate calls

By default, the TOPdesk mail import turns an email into a new card, such as a call, unless the subject contains the number of an existing card. A single question can therefore produce several calls. A reply without a number becomes a second call. Extra calls also appear when colleagues all reply in an email thread, or when an out-of-office reply comes back. For each situation, the sections below explain what TOPdesk does and what you set in the mail import. The names of menus and settings follow the TOPdesk SaaS documentation.

Card type and caller

The mail import reads a mailbox and registers each email as a first-line call, a second-line call or a request for change. You set the card type for each mail import under Settings > Import settings > Mail import, together with default values such as category and operator. If emails arrive at more than one address, TOPdesk advises giving each address its own mail import.

The sender becomes the caller if TOPdesk finds the address on a person card that is not archived. For an unknown sender, step 4 of the Guided setup gives you three options: fill in only the email address, create a new person card or do not import the email. The second option can create a duplicate person card when someone who already has a person card emails from a different address.

Replies to an existing call

TOPdesk uses the number in the subject to tell whether an email belongs to an existing card. If the subject contains the number of an existing call, change or change activity, TOPdesk updates the matching card, even if it is archived. Without a number, a new card is created. So put the call number in the subject of every email that callers receive from TOPdesk, as Migrating to TOPdesk also advises.

You decide what happens next for each mail import, in step 5 of the Guided setup. The page References to existing cards describes three cases:

• Open call: you choose which status the mail import sets.
• Completed or closed call: by default, the mail import adds the email and changes the status. You can also choose a new call instead; the old call then stays completed or closed.
• Change or activity: the mail import adds the email, but does not change the status.

If a reply carries the whole thread below it, Only import replies leaves out everything after a marker that an email client adds when replying. The option only works for emails that refer to an existing card. You add your own markers, such as the line with the service desk's sender address, under Email markers.

Why does the same email thread produce several calls?

Every message without a call number in the subject becomes a new call. Suppose an email from outside also reaches the mail import through a distribution list. If colleagues use Reply All, each reply becomes a call of its own. According to the documentation, the mail import can also read from a separate folder, with an email rule in the mailbox routing the right messages there.

Automatic email from another system causes a similar problem. TOPdesk's best practices for performance advise against sending automatic emails to a mail import address. For a system that creates calls through the API, the page advises against sending the same API call over and over; see also Integrating with the TOPdesk API.

How do you stop an out-of-office reply from becoming a call?

Within TOPdesk, you tick Suppress automatic replies for each email action. TOPdesk recommends ticking it to prevent a loop. An email action in the Action Explorer has the same option. According to Creating actions, the email then gets headers that suppress automatic replies. More on email actions in Events and actions in TOPdesk.

If an out-of-office reply does come in, the subject decides what happens. Without the original subject, a new card is created, and according to the documentation an acknowledgement is then likely to follow. If the reply keeps the subject with the call number, the mail import sets the status from step 5 on an open call. A call that was waiting for the caller then appears to have been answered. Recommendations against mail loops are in KI 10145 on My TOPdesk.

Events on calls from the mail import

According to the release notes, since release 16.05.011 of 15 May 2026 the mail import in TOPdesk SaaS can trigger regular events when it creates or updates a card. Previously, only a Card date event worked. You enable the option for each mail import, in step 6 under Event triggers. More on the transition is in KI 19215 on My TOPdesk. Before you enable the option, TOPdesk recommends a few steps:

1. Review events: check which existing events respond to cards being created and updated, such as New card and Edit card.
2. Clear out workarounds: remove workaround events created specifically for the mail import. TOPdesk states in the community (29 January 2026) that a Card date event lets you start actions after the mail import (community post 293).
3. Filter on entry type: if an event should only apply to the mail import, filter on the entry type and not on a custom operator. TOPdesk recommends keeping the default operator, TOPdesk Mail Import Service, because a different operator can make reporting and troubleshooting harder.

With the option on, a mail import behaves, according to TOPdesk, the same as other ways of creating or updating cards. An acknowledgement on New card can then fire for email too. Take extra care with out-of-office replies, because an acknowledgement to an automatic reply can lead to another automatic reply. The description of the event triggers reflects the situation in October 2026, based on TOPdesk's documentation and release notes.

Where can you see why an email was not imported?

If a mail import fails, operators with permissions for the mail import settings see a banner. You look for the cause in the execution logs, which you open from the overview under Settings > Import settings > Mail import or from the mail import itself. The logs show which emails were imported, which cards were created or updated and which errors occurred. More advice is in KI 8765 on My TOPdesk.

Two settings help when you investigate:

• Folders after importing: TOPdesk recommends moving imported emails to a folder such as Successfully Imported, and the rest to Not Imported. TOPdesk advises against deleting them, because deleted emails cannot be recovered.
• Failure notifications: an email to one or more recipients when a mail import fails and, if you choose, also when an email from an unknown sender has not been imported. According to the documentation, TOPdesk deactivates a mail import that fails seven days in a row.

What to record during setup

For each mail import, record:

• Connection: which type of mailbox the mail import uses and, with Microsoft Graph, which app registration in Microsoft Entra ID belongs to it. TOPdesk recommends Microsoft Graph or Gmail, because both work with OAuth 2.0. According to the documentation, the Mail.ReadWrite permission of the app registration applies to all mailboxes in the Microsoft 365 tenant; how to restrict the permission to a single mailbox is described in KI 12589 on My TOPdesk.
• Certificate or secret: TOPdesk recommends a client certificate and warns thirty days before the certificate expires. You renew a client secret by hand for each mail import. Record who manages the app registration, as TOPdesk administrator leaving also advises.
• Choices per step: the folders and mailbox rules, unknown senders, the status on a reply and whether events fire, with the reason for each choice.
• Notifications and permissions: who receives the failure notifications, who may change the settings and who may view the logs. You set the permissions on the permission group, in the Mail import block; viewing the logs is a separate permission there.

We set up the mail import as part of our TOPdesk consultancy, together with the events and actions that go with it. Depending on the agreement, we arrange the mailbox rules and the app registration in Microsoft Entra ID ourselves, with the access clients give us for that purpose, leave them to their IT department or do them together.