Link Email to Case

Note

This tool is available by default on the following MCP servers: Dynamics 365 Customer Service. The tools and examples in this documentation illustrate current capabilities. Tool names, descriptions, parameters, response formats, and available functionality can change over time.
When you build agents, integrations, or orchestration logic, don't hard-code dependencies on specific tool names, parameter structures, tool metadata, or response schemas. Instead, design your solution to discover and use available tools at runtime.
As the platform evolves, Microsoft might add, remove, rename, or modify tools and tool metadata. Designing against capabilities rather than specific tool identifiers helps maintain compatibility across service updates.

Use this capability when you have an email that should be associated with an existing case. Linking connects the email to the case so it appears on the case's timeline.

What it does

The assistant links an email to a case by setting the email's "regarding" reference to the target case. Once linked, the email appears on the case's activity timeline alongside other emails, notes, and activities. This is useful for organizing unlinked emails or associating an email with the correct case.

Try prompts like

• "Link this email to case CAS-01010-A0A0A0"
• "Associate the email with this case"
• "Connect the email to the case"
• "Attach the customer's email to the billing case"
• "Link it to the case we found"

What you see in chat

The assistant shows a text confirmation that the email was successfully linked to the case. No interactive component appears.

Helpful tips

• If you're not sure which case to link the email to, say "match this email to existing cases" first. The assistant finds cases that might be a good fit.
• Linking an email to a case is safe to repeat - linking the same email to the same case again doesn't create duplicates.
• If no existing case matches the email, say "create a case from this email" instead.

Tip

A common workflow is: view email, match it to cases, then link it to the best match - or create a new case if none match.

What happens next

After the email is linked, you can continue with prompts like:

• "Open the case"
• "Show the case timeline"
• "Summarize the case"
• "Are there more unlinked emails?"

Does this change data?

Yes. This links the email to the case.

The email's regarding reference is updated in Dynamics 365 to point to the case. The assistant asks for confirmation before making the change.

Prerequisites

This tool requires the following:

• Email

Learn more in Configure email.

Tool summary

Property	Value
User-facing name	Link Email to Case
Internal tool name	link_email_to_case
Purpose	Links an email activity to an existing case by setting the email's regarding object to the target case

Tool behavior

Links an email activity to an existing case by setting the email's regarding object to the target case. Use after match_cases when the agent selects an existing case to associate an unlinked email with.

Annotations

Annotation	Value	Meaning
readOnlyHint	false	This tool modifies data - Microsoft 365 Copilot prompts for confirmation.
destructiveHint	false	Linking is not destructive (the email still exists).
idempotentHint	true	Re-linking the same email to the same case produces the same result - safe to retry.
openWorldHint	Not set	Uses default (queries Dataverse).

Input concepts

Email identifier

Input	Description	Required
activityId	activityId (the Dataverse email activity GUID to link, required).	Yes

Target case

Input	Description	Required
incidentId	incidentId (the target case GUID to link the email to, required).	Yes

Response and UI behavior

Response type

Text-only

No interactive component is rendered. The tool returns a confirmation that the email was linked to the case.

Routing notes

Use link_email_to_case for:

• "Link the email to this case", "associate the email with the case"
• After match_cases identifies an existing case for an unlinked email

Don't use link_email_to_case when:

• No existing case matches the email and a new case is needed - use create_case_from_email
• The user wants to find matching cases first - use match_cases

Related tools

Tool	Relationship
match_cases	Finds existing cases that may match an email (called before linking)
create_case_from_email	Creates a new case when no existing case matches
view_email	Displays the email content before linking

Data mutation classification

Write / mutation.

This tool updates the email's regarding object reference in Dataverse. M365 Copilot prompts the user for confirmation. The operation is idempotent - re-linking the same email to the same case produces the same result.