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 or disabled, restricted by sender domain, and configured to auto-create tickets with consistent titles, descriptions, assignees, ticket defaults, and optional ticket-channel routing.

In the KDesk App, open the Team navigation and select Email Intake. The page title is Email Intake Integration. If you do not see it, your team must have Enable channels turned on in Team Settings > Integrations > Inbound channels, your account must have permission to manage integrations, and the provider you want to use must be allowed there as well. This page is only available to team members, not contact users.

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 mailboxes and/or Google Workspace / Gmail. If channels are disabled at the team level, the Email Intake menu is hidden and 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. The page also shows summary cards for Captured emails today, Auto-created tickets, and Active inboxes, plus a recent ticket feed and per-inbox counters for new emails, auto tickets, and last activity.

You can manually trigger intake using the page controls. Run all processes every connected inbox, Run processes a single inbox, and Process tickets runs the team queue through ticket creation. Each inbox card also has an action menu for Manage, Run, View activity, and Delete.

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).

Note: Legacy Gmail IMAP inboxes may still appear in the list as Gmail (legacy IMAP, disabled). They cannot be managed from the current builder. Create a new Google Workspace inbox instead.

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.
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 with client credentials to access a mailbox. In KDesk, you 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, make sure 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 or folders KDesk reads from. New inboxes default to INBOX.
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, ticket channel, 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.
Ticket channel	Routes the created ticket to a different channel if needed; leave blank to use this inbox.
Create as closed ticket	Creates tickets directly in a closed state, which is 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 confirm that emails are flowing and tickets are being created. The page updates the summary cards as messages are processed, and the Recent tickets feed shows the latest intake activity. Use Refresh to reload channel data after changes. Open an inbox's View activity action to inspect its processing logs, or use Run and Run all to trigger intake manually.

If tickets are not appearing, first confirm that the team has channels enabled, the inbox is enabled, Receive is on, and the provider-specific allow toggle for Microsoft 365 or Google Workspace / Gmail is enabled in Team Settings. Then check whether Domain lock or the Gmail Query filter is excluding your test message, and make sure Auto-create tickets is enabled if you expect tickets to be created automatically.

If you need deeper visibility, open channel activity logs from within Email Intake to see recent processing events and how messages were handled. From the activity modal, View more downloads the full log entry as text.