# Pipedrive Mail MCP

> Pipedrive Mail lets your AI agent read, list, and process entire email threads directly linked to deals within Pipedrive CRM. Instead of switching tabs or copying data into a chat window, you manage all sales communication—notes, contacts, deal status, and message history—all through conversation.

## Overview
- **Category:** communication-tools
- **Price:** Free
- **Tags:** email-integration, communication-tracking, sales-outreach, crm-sync

## Description

Listen up. This isn't just another API connection; this is how you stop wasting time clicking between tabs when you’re managing deals in Pipedrive. You connect your AI agent, and it treats all your sales communication—the whole messy thread of emails—as one live context right inside the chat client. You don't have to copy and paste anything anymore.

The entire system revolves around keeping every piece of correspondence linked directly to a specific deal record. It starts with finding what you need. When you want to know what communications exist for a particular opportunity, your agent uses `pd_list_mail_threads`. This tool pulls a complete list of unique mail threads tied to deals or contacts, giving you an immediate overview of the history without you having to guess which thread is relevant.

Once you've identified the right conversation, pulling its full context is simple. To get all the details—the entire back-and-forth, including replies and forwards—your agent calls `pd_get_mail_thread`. This single command pulls every bit of information for an entire email conversation thread, giving you the sequence and chronology needed to understand exactly what was said and when. You've got the full story right there.

If you need granularity, or maybe just want to pull specific data points from that massive thread history, `pd_get_mail_messages` is your play. This tool retrieves a detailed list of individual messages within a given mail thread ID, fetching both the message body and all relevant metadata for each one. You get more than just text; you're pulling date stamps, sender info, and every other detail that matters.

After your agent pulls all this raw context—the full threads, the individual messages, the list of associated conversations—you need to make sure it sticks to the right record. That’s where `pd_deal_mail` steps in. You use this tool to connect specific email records or entire communication threads directly back to a deal record inside Pipedrive CRM. It ensures that when your agent talks about 'the last conversation,' you know exactly which deal we're talking about.

When the AI client runs these tools, it pulls structured data—messages, metadata, dates, and thread IDs—and then presents that raw context back to you in a conversational format. You don't see code; you just see the facts. You can ask follow-up questions immediately based on that history, or prompt an action using the gathered information. It’s about turning historical data into actionable dialogue.

Imagine this: Instead of opening Pipedrive, finding the deal, clicking 'Activity,' scrolling through emails, copying a key date, and pasting it elsewhere—your agent does all that work for you in one go. You use `pd_list_mail_threads` to scope out the threads associated with a contact or deal. Then, using `pd_get_mail_thread`, you pull the complete conversation history. If you only need the message text and not the thread structure, you can pinpoint it using `pd_get_mail_messages`. Every time an email is processed, `pd_deal_mail` makes sure that communication is officially logged against the deal record. This whole process means your AI agent manages all sales communications—the notes, the contacts, the status updates, and the message history—all through conversation. You stay in your chat client; you never leave it.

The combination of listing threads with `pd_list_mail_threads`, getting full details with `pd_get_mail_thread`, fetching specifics with `pd_get_mail_messages`, and finally linking everything with `pd_deal_mail` means you're dealing in one central, conversational context. You get the raw data, but your agent gives you the intelligence on top of it.

## Tools

### pd_deal_mail
Links specific email communications to a deal record in Pipedrive.

### pd_get_mail_messages
Retrieves the body and metadata for multiple individual messages within a thread ID.

### pd_get_mail_thread
Pulls all details, including message sequence and replies, for an entire email conversation thread.

### pd_list_mail_threads
Returns a list of unique mail threads associated with deals or contacts.

## Prompt Examples

**Prompt:** 
```
Search for deals with Acme Corp
```

**Response:** 
```
📊 **Deals with Acme Corp**
| Title | Value | Stage | Pipeline |
|---|---|---|---|
| Acme Enterprise License | $45,000 | Proposal Made | Sales Pipeline |
| Acme Support Plan | $12,000 | Won | Renewals |
```

**Prompt:** 
```
Create a call activity for tomorrow at 2pm
```

**Response:** 
```
✅ **Activity Created!**
- Type: Call
- Subject: Follow-up call
- Due: Tomorrow at 2:00 PM
- Status: Pending
```

**Prompt:** 
```
Show me the pipeline stages
```

**Response:** 
```
📦 **Sales Pipeline**
1. Lead In
2. Contact Made
3. Prospect Qualified
4. Proposal Made
5. Negotiations Started
6. Won ✅
7. Lost ❌
```

## Capabilities

### List All Deal Mail Threads
Use `pd_list_mail_threads` to pull a list of all email threads associated with a specific deal ID.

### Get Full Email Thread Details
Pull the complete conversation history, including replies and forwards, for one thread using `pd_get_mail_thread`.

### Retrieve Individual Messages
Fetch a list of individual messages within a given mail thread ID via `pd_get_mail_messages`.

### Link Emails to Deals
Use `pd_deal_mail` to connect specific email records or threads directly to a deal record in the CRM.

## Use Cases

### The SDR needs context on an old lead.
A new SDR gets a cold call from a prospect, Acme Corp. The agent uses `pd_list_mail_threads` to find all previous comms for Acme Corp's associated deal. It then calls `pd_get_mail_thread` and summarizes the key pain points mentioned weeks ago, allowing the SDR to start the conversation with relevant knowledge.

### The AE needs a status update on a stalled deal.
An Account Executive reviews 'Deal X' before sending a follow-up. The agent calls `pd_get_mail_messages` for the last three emails, confirming that the client responded with specific objections about pricing. This detail prevents the AE from making assumptions and ensures the follow-up is targeted.

### The Manager needs a full pipeline review.
A Sales Manager asks to see all 'Proposal Made' deals that have had communication in the last 7 days. The agent uses `pd_list_mail_threads` and filters by stage, giving the manager an immediate overview of activity volume for targeted coaching.

### The RevOps needs to audit a deal record.
RevOps wants proof that all client communications are logged. They ask the agent to confirm if the final signed contract email was properly linked using `pd_deal_mail` and provide the full thread history via `pd_get_mail_thread` for compliance checks.

## Benefits

- Review the full context before talking to a client. By calling `pd_get_mail_thread`, your agent pulls every message exchange related to a deal, so you never miss historical details or commitments.
- Keep data structured without tabs. You use `pd_list_mail_threads` to see all recent activity for multiple deals at once, giving instant visibility into where the pipeline stands across several accounts.
- Build records from conversations. After reviewing emails, you can ask your agent to create a new 'Call' or 'Note' activity using the deal context, logging the interaction immediately.
- Rapidly find key people. You use contact tools (available in the main CRM listing) combined with mail data to quickly identify who was on which thread and what their role is.
- Automate reporting prep. Instead of manually gathering emails for a weekly review, your agent pulls structured deal data *and* linked comms using `pd_deal_mail`, ready for your report.

## How It Works

The bottom line is that your agent establishes a dependency chain: listing threads first, then pulling specific content for analysis.

1. Start by calling `pd_list_mail_threads` to identify which conversation history you need (e.g., 'Show me all threads for Acme Corp').
2. Select a thread ID, then call `pd_get_mail_thread` or `pd_get_mail_messages` to pull the full message content and metadata.
3. The agent processes this data, presenting it to you in formatted text. You can then ask follow-up questions (e.g., 'What was their pain point mentioned in the last email?').

## Frequently Asked Questions

**How does pd_list_mail_threads work with deals?**
It lists all unique email threads associated with a deal ID or contact record. This tool gives you the IDs necessary to then pull full conversation details using `pd_get_mail_thread`.

**Can I use pd_deal_mail to update a record?**
No, `pd_deal_mail` is specifically for linking emails/threads to deals. You'll need separate tools or prompts to actually update the deal status or add notes.

**What’s the difference between pd_get_mail_thread and pd_get_mail_messages?**
Use `pd_get_mail_thread` when you want the full, chronological narrative of the conversation. Use `pd_get_mail_messages` when you just need a bulleted list of individual messages within that thread.

**Does Pipedrive Mail support historical data?**
Yes. The tools are designed to retrieve and process message history, allowing your agent to build context from communications that happened weeks or months ago.

**How do I use pd_list_mail_threads to filter results?**
You can pass specific date ranges or deal IDs when calling `pd_list_mail_threads`. The tool filters the list of threads based on your input parameters, allowing you to narrow down communication history quickly.

**What happens if I use pd_get_mail_messages with an invalid thread ID?**
The server returns a specific error code and message detailing the invalid identifier. Your AI client catches this error, so you can easily prompt for correction or try retrieving messages from a different source.

**Are there rate limits when I call pd_deal_mail repeatedly?**
Vinkius enforces standard API rate limits to ensure stability. If your agent makes too many calls in a short period, you'll receive a 429 error; simply wait a moment or implement exponential backoff in your workflow.

**Does pd_get_mail_thread provide sender and recipient metadata?**
Yes, `pd_get_mail_thread` returns comprehensive metadata for every participant. You get the full names, email addresses, and internal Pipedrive IDs for both the sender and recipients.

**What Pipedrive data can I access?**
Deals, Persons, Organizations, Activities, Notes, and Pipelines. All data respects your Pipedrive permissions.

**Can I create and update records?**
Yes! Create and update deals, contacts, activities, and notes — all through natural conversation.

**How does authentication work?**
Uses your personal Pipedrive API token. Find it in Settings > Personal preferences > API. No OAuth flow needed.