KDesk Email Intergration

Email Intake Integration (Ticket Inbox)

KDesk Email Intake turns inbound email into tickets by connecting a mailbox to your team. Each connected inbox can be enabled/disabled, restricted by sender domain, and configured to auto-create tickets with consistent titles, descriptions, assignments, and defaults.

This page is found in the KDesk App under the navigation menu as Email Intake Intergration. If you do not see Email Intake, an owner must enable channels in Team Settings and allow the provider you want to use. Also check if you have permission to modify intergrations.

Prerequisites (Team Settings)

Email Intake is controlled by Team Settings. In Team Settings → Integrations → Inbound channels, enable Enable channels. Then enable the provider you plan to connect (Microsoft 365 and/or Google Workspace). If channels are disabled at the team level, inbox connections will not function.

How Email Intake Works

Each inbox connection stores a provider configuration and an optional ticket-creation rule. When messages are received, KDesk can automatically create tickets using your title and description templates. You can monitor activity and manually trigger processing using the Run controls in the Email Intake page.

Important: Email Intake templates use {curlyBraceTokens} (for example, {email.subject}). These are separate from outbound notification email templates in Team Settings, which use $dollarTokens (for example, $ticketNumber).

Inbox Settings Reference (Details Tab)

Setting	What it does
Inbox name	Display name for the connected inbox inside KDesk.
Provider	Selects the connection method: Microsoft 365 or Google Workspace (service account).
Enabled	Turns the inbox on or off without deleting its configuration.
Receive	Controls whether the inbox pulls inbound email for ticket creation.
Send	Controls whether the inbox is allowed to send through the channel (if your environment supports sending).
Domain lock	Restricts which sender domains are accepted for intake (enter domains like example.com, without the @). Leave blank to accept any domain.

Provider Setup: Microsoft Entra (Microsoft 365)

The Microsoft 365 provider uses an Entra application (client credentials) to access a mailbox. In KDesk, you will provide the mailbox identity plus Entra app identifiers. KDesk requires a client secret to be present; when editing an existing inbox, you can leave the secret blank to keep the stored one, or paste a new secret to rotate it.

Field in KDesk	What to enter	Notes
Mailbox (UPN/shared)	The mailbox address or UPN, such as support@company.com	This can be a user mailbox or a shared mailbox, depending on your Entra/Exchange setup.
Tenant ID	Your Entra tenant (directory) ID	GUID format (for example 95dd9b68-…).
Client ID	The Application (client) ID from your Entra app registration	Enter the client ID, not the secret ID.
Client secret	A valid client secret value for the Entra app	Required when creating a new inbox; optional when editing if a secret is already stored.

In Entra, create (or reuse) an app registration and grant it permission to read mail for the mailbox you are connecting, then approve admin consent per your organization’s policy. If your organization restricts application access to specific mailboxes, ensure the app is allowed to access the mailbox you enter in KDesk.

Provider Setup: Google Workspace (Gmail API / Service Account)

The Google Workspace provider uses a Google service account with domain-wide delegation, plus a delegated user (the mailbox user you want to impersonate for reading mail). KDesk validates that a delegated user is present, and it requires a service account JSON key to be present. When editing an existing inbox, you can leave the JSON field blank to keep the stored key, or paste a new JSON to rotate it.

Field in KDesk	What to enter	Notes
Delegated user	A Workspace user email, such as groupmember@company.com	This user is impersonated via domain-wide delegation for mailbox access.
Mailbox (optional userId)	Usually me	If blank, KDesk defaults to me. This is the Gmail API userId value.
Service account JSON	The full JSON key content for your service account	Required for new inboxes; optional during edit if a key is already stored.
Labels (comma separated)	For example INBOX	Controls which labels/folders KDesk reads from.
Query (Gmail search)	Optional Gmail search query, for example after:2025/01/01 -category:promotions	Use this to exclude noise and scope what becomes tickets.

Ticket Creation (Templates and Defaults)

Each inbox can auto-create tickets. When enabled, KDesk uses your title and description templates to generate the ticket’s initial content. You can also set defaults for assignees (users and groups), category, status, priority, and optionally create the ticket as closed. If you disable auto-create, messages can still be pulled and observed in channel activity, but tickets will not be created automatically.

Setting	What it does
Auto-create tickets	Creates a ticket automatically for each eligible inbound message.
Title template	Creates the ticket title (defaults to [Inbox] {email.subject}).
Description template	Creates the ticket description (defaults to From: {email.from} plus {email.bodyText}).
Assignees (users and groups)	Auto-assigns created tickets to specific responders or groups.
Category / Status / Priority	Applies defaults to created tickets; choose “Default” to use your team’s default settings.
Create as closed ticket	Creates tickets directly in a closed state (useful for archival intake flows).

Template Variables (Email Intake Tokens)

Email Intake templates support the following tokens. These tokens are used only in the Email Intake “Title template” and “Description template” fields.

Token	Meaning
{channelName}	Channel name
{channel.oid}	Channel ID
{email.subject}	Email subject
{email.from}	From address
{email.to}	To addresses (comma separated)
{email.cc}	CC addresses (comma separated)
{email.bcc}	BCC addresses (comma separated)
{email.bodyText}	Plaintext body
{email.bodyHtml}	HTML body
{email.sentAt}	Sent timestamp (ISO)
{email.receivedAt}	Received timestamp (ISO)
{email.providerMessageId}	Provider message ID

Recommended Templates (Copy/Paste)

These examples are designed to create consistent, searchable tickets while keeping the original email context.

Title template

[{channelName}] {email.subject}

Description template (plaintext)

Channel: {channelName} From: {email.from} To: {email.to} CC: {email.cc} Sent: {email.sentAt} Received: {email.receivedAt}
{email.bodyText}

Description template (HTML-aware, fallback-friendly)

Channel: {channelName} From: {email.from} To: {email.to} CC: {email.cc} Sent: {email.sentAt} Received: {email.receivedAt}
{email.bodyHtml}

Testing, Monitoring, and Troubleshooting

After saving an inbox, use the Email Intake page to monitor inbound activity and confirm ticket creation. The page shows recent tickets and per-inbox metrics such as new emails and auto tickets, which are updated as messages are processed. If tickets are not appearing, first confirm the team has channels enabled, the inbox is enabled and set to Receive, and that domain lock or Gmail query filters are not excluding your test message.

If you need deeper visibility, open channel activity logs from within Email Intake to see recent processing events and how messages were handled.