---
title: PM Email Integration (link emails to PM items)
---

# PM Email Integration (link emails to PM items)

## What it is

An in-development integration bridging PM items with Gmail, Agent Email, and Supermail. It closes the
gap between the conversation and the work: an email thread and a board item can point at each other,
and the item can be created straight from the email that prompted it.

## Where to find it

The feature spans all three email surfaces:

- **Gmail viewer** -- PM action buttons and linked-item chips on email threads.
- **Agent Email** -- hover-reveal PM actions on email rows.
- **Supermail** -- native PM chips in conversations plus "create task" and
  "link to task" triage actions.

It is in development, gated behind `pm-email-integration` in `UNRELEASED_FEATURES`, and it requires
both `missionControlEnabled` AND `pmEmailIntegrationEnabled` (a double gate on every IPC handler). It
is desktop-only — all 7 IPC channels are blocked from the WebSocket/mobile bridge — so none of the
above appears on a phone.

## How it behaves

Users can link email threads to PM items, create new PM items directly from
emails, and set up workflow automations triggered by incoming emails.

The PM item detail drawer shows a "Linked emails" section listing linked email
threads. An incoming Gmail message that matches a workflow's email trigger (sender,
subject or label) starts that workflow.

## For agents

Links are stored in the generic `pm_item_links` table with
`entity_type = 'email_thread'` and a source label (`gmail`, `agent-email`,
`supermail`). Duplicate links return the existing link instead of throwing.

- Backend: `src/main/services/pm/email/pm-email-link-service.ts` (CRUD + push on
  every mutation).
- 7 IPC handlers in `pm-email-handlers.ts`.
- Workflow trigger: `src/main/services/workflow-engine/email-trigger.ts` — evaluated inside
  `evaluateMessageWorkflows`, so an incoming Gmail message starts a `trigger.email` workflow only
  when the workflow is approved, the sender passes the inbound sender gate, and both switches
  (Mission Control and PM email integration) are on.
- Contract: `pm-email-integration-contract.md`.

## Related

This is a specific use of the general linking system, so
[pm-cross-entity-links.md](pm-cross-entity-links.md) is the place to start — it explains the Links
tab, the picker, and what happens when you unlink. The email ends of the bridge have their own pages:
[agent-email.md](agent-email.md) covers Agent Email and [supermail.md](supermail.md) covers Supermail.
The automations an incoming email can trigger are described in
[workflows.md](workflows.md) and [automations-and-auto-replies.md](automations-and-auto-replies.md).
The items themselves belong to [mission-control.md](mission-control.md).