# Email tools

> Every email tool in the developer API, with arguments and examples: search, read, draft, send and organise email.

**Needs:** Gmail, Outlook, iCloud Mail, Yahoo or any IMAP mailbox. 9 tools.

These tools appear in `GET /v1/tools` only when the API key's MCP server includes a connection of this kind. Call each one with `POST /v1/tools/\<name>`, sending its arguments as a JSON object. See [Calling tools](https://docs.plugsight.app/developers/calling-tools.md) for the request and response format.

| Tool                                  | What it does                  | Kind   |
| ------------------------------------- | ----------------------------- | ------ |
| [`list_folders`](#list_folders)       | List folders                  | Read   |
| [`search_emails`](#search_emails)     | Search / list emails          | Read   |
| [`get_email`](#get_email)             | Read an email                 | Read   |
| [`get_thread`](#get_thread)           | Read a conversation           | Read   |
| [`get_attachment`](#get_attachment)   | Read an attachment            | Read   |
| [`create_draft`](#create_draft)       | Create a draft                | Change |
| [`send_email`](#send_email)           | Send an email                 | Change |
| [`organize_emails`](#organize_emails) | Archive, label or mark emails | Change |
| [`send_draft`](#send_draft)           | Send a draft                  | Change |

Change tools in this group: `create_draft`, `send_email`, `organize_emails`, `send_draft`. Check each tool's notes below for what it needs before it runs.

The example requests fill in only the required arguments, with placeholder values. Replace `ACCOUNT_ID` with an `id` from [`list_accounts`](https://docs.plugsight.app/developers/accounts-tools.md).

## list_folders

**List folders** · Read

Lists folders/labels of one account with message and unread counts.

| Argument  | Type   | Required | What it is                    |
| --------- | ------ | -------- | ----------------------------- |
| `account` | string | Yes      | Account id from list_accounts |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/list_folders \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account": "ACCOUNT_ID"}'
```

## search_emails

**Search / list emails** · Read

Lists or searches emails across one or all accounts. All filters combine with AND; a list (e.g. from: ["a@x.com", "b@y.com"]) matches any entry. With no filters it lists the latest inbox emails. Results include a short preview and the attachment list. `query` is a text match; on Gmail accounts it also accepts Gmail search syntax (e.g. "from:amazon newer_than:7d"), on Outlook accounts Outlook search syntax (e.g. "from:amazon AND received>=2026-01-01"). Searches run live against each mail server and cover the whole mailbox history. For "find all" questions, keep paging with offset until no more results come back. When more_per_account lists an account, its results are incomplete or can continue: follow its note, e.g. call again for that account with cursor: next_cursor.

| Argument          | Type                      | Required | What it is                                                                                                                                   |
| ----------------- | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `account`         | string                    | No       | Account id, or "all" (default)                                                                                                               |
| `folder`          | string                    | No       | Folder path from list_folders, or: inbox (default), sent, drafts, trash, junk, archive, all (every folder except trash/junk)                 |
| `query`           | string                    | No       | Free text anywhere in the email                                                                                                              |
| `from`            | string or array of string | No       | Sender name/address contains (string or list, any match)                                                                                     |
| `to`              | string or array of string | No       | Recipient (To) contains                                                                                                                      |
| `cc`              | string or array of string | No       | Cc contains                                                                                                                                  |
| `bcc`             | string or array of string | No       | Bcc contains (only visible on emails you sent)                                                                                               |
| `subject`         | string                    | No       | Subject contains                                                                                                                             |
| `body`            | string                    | No       | Body contains                                                                                                                                |
| `exclude_from`    | string or array of string | No       | Leave out emails from these senders                                                                                                          |
| `exclude_subject` | string                    | No       | Leave out emails whose subject contains this                                                                                                 |
| `exclude_text`    | string                    | No       | Leave out emails containing this text                                                                                                        |
| `since`           | string                    | No       | On or after this date, YYYY-MM-DD                                                                                                            |
| `before`          | string                    | No       | Before this date, YYYY-MM-DD                                                                                                                 |
| `unread`          | boolean                   | No       | true = only unread, false = only read                                                                                                        |
| `flagged`         | boolean                   | No       | true = only flagged/starred, false = only unflagged                                                                                          |
| `answered`        | boolean                   | No       | true = only emails you replied to, false = not replied                                                                                       |
| `has_attachment`  | boolean                   | No       | true = has real attachments (images embedded in the body don't count), false = none                                                          |
| `attachment_name` | string                    | No       | An attachment's filename contains this                                                                                                       |
| `attachment_type` | string                    | No       | Has an attachment of this type: pdf, image, document, spreadsheet, presentation, calendar, archive, email, audio, video, or a file extension |
| `larger_than_kb`  | number                    | No       | Email size above this many KB                                                                                                                |
| `smaller_than_kb` | number                    | No       | Email size below this many KB                                                                                                                |
| `sort`            | string                    | No       | Sort order. One of: `newest`, `oldest`. Default `"newest"`.                                                                                  |
| `include_preview` | boolean                   | No       | Include a ~200 character body preview. Default `true`.                                                                                       |
| `limit`           | integer                   | No       | Most results to return. Default `20`.                                                                                                        |
| `offset`          | integer                   | No       | Skip this many results (pagination) Default `0`.                                                                                             |
| `cursor`          | string                    | No       | next_cursor from an earlier result (Outlook): continues that search where it stopped. Needs the same account and filters; offset must be 0   |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/search_emails \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## get_email

**Read an email** · Read

Returns the full email: headers, body text and the attachment list. Images embedded in the body are listed with inline: true and marked in the text as [inline image #N]; read them with get_attachment. Links in HTML emails are kept as "text (url)". Does not mark the email as read.

| Argument          | Type    | Required | What it is                                                                                             |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `account`         | string  | Yes      | Account id from list_accounts                                                                          |
| `email_id`        | string  | Yes      | Email id from search_emails                                                                            |
| `include_html`    | boolean | No       | Also return the raw HTML body. Default `false`.                                                        |
| `include_headers` | boolean | No       | Also return all raw headers (e.g. List-Unsubscribe, Received, authentication results) Default `false`. |
| `max_chars`       | integer | No       | Truncate body to this many characters. Default `20000`.                                                |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/get_email \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account": "ACCOUNT_ID", "email_id": "…"}'
```

## get_thread

**Read a conversation** · Read

Returns every email in the same conversation as the given email, oldest first.

| Argument              | Type    | Required | What it is                                                        |
| --------------------- | ------- | -------- | ----------------------------------------------------------------- |
| `account`             | string  | Yes      | Account id from list_accounts                                     |
| `email_id`            | string  | Yes      | Email id from search_emails                                       |
| `max_chars_per_email` | integer | No       | Longest email text returned; longer ones are cut. Default `5000`. |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/get_thread \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account": "ACCOUNT_ID", "email_id": "…"}'
```

## get_attachment

**Read an attachment** · Read

Reads one attachment, including images embedded in the body. `attachment` is the index from get_email; for files inside a forwarded email (.eml) or Outlook winmail.dat use a path like "2.0". Returned as text for PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), HTML, CSV and other text files; as an image for images. Use mode "base64" to get the raw file instead.

| Argument     | Type              | Required | What it is                                                                                                      |
| ------------ | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `account`    | string            | Yes      | Account id from list_accounts                                                                                   |
| `email_id`   | string            | Yes      | Email id from search_emails                                                                                     |
| `attachment` | integer or string | Yes      | Index from get_email (e.g. 0), or a nested path (e.g. "2.0")                                                    |
| `mode`       | string            | No       | auto: text when the file can be read as text; base64: the raw file. One of: `auto`, `base64`. Default `"auto"`. |
| `max_chars`  | integer           | No       | Truncate extracted text. Default `50000`.                                                                       |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/get_attachment \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account": "ACCOUNT_ID", "email_id": "…", "attachment": 1}'
```

## create_draft

**Create a draft** · Change

Saves an email as a draft in the account's Drafts folder; nothing is sent. Supports new emails, replies (reply_to_email_id, reply_all) and forwards (forward_email_id), with attachments uploaded as base64 or copied from another email.

> [!NOTE]
> This saves a draft in the mailbox and never sends anything. It needs no `confirm`, and it works even when sending is off for the account or the MCP server.

| Argument            | Type                      | Required | What it is                                                                           |
| ------------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------ |
| `account`           | string                    | Yes      | Account id to send from (list_accounts)                                              |
| `to`                | string or array of string | No       | Recipients: address or "Name \<address>" (string or list)                            |
| `cc`                | string or array of string | No       | Cc recipients: address or list                                                       |
| `bcc`               | string or array of string | No       | Bcc recipients: address or list                                                      |
| `subject`           | string                    | No       | Subject. Defaults to "Re: …" / "Fwd: …" for replies and forwards                     |
| `body`              | string                    | Yes      | Plain-text body. For replies/forwards the original is quoted below it automatically  |
| `reply_to_email_id` | string                    | No       | Reply to this email (sender is added as recipient, threading kept)                   |
| `reply_all`         | boolean                   | No       | With reply_to_email_id: also include the original To and Cc. Default `false`.        |
| `forward_email_id`  | string                    | No       | Forward this email, including its attachments                                        |
| `attachments`       | array of object           | No       | Files to attach: email_id + attachment index from an email, or name + base64 content |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/create_draft \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account": "ACCOUNT_ID", "body": "…"}'
```

## send_email

**Send an email** · Change

Sends an email immediately (new, reply or forward). Sending must be allowed for the account and this MCP in the app, and is limited per day; if blocked, offer create_draft instead.

> [!IMPORTANT]
> This tool makes a change, so the request must include `"confirm": true`, and changes must be allowed. See [Making changes](https://docs.plugsight.app/developers/calling-tools.md#making-changes).

| Argument            | Type                      | Required | What it is                                                                           |
| ------------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------ |
| `account`           | string                    | Yes      | Account id to send from (list_accounts)                                              |
| `to`                | string or array of string | No       | Recipients: address or "Name \<address>" (string or list)                            |
| `cc`                | string or array of string | No       | Cc recipients: address or list                                                       |
| `bcc`               | string or array of string | No       | Bcc recipients: address or list                                                      |
| `subject`           | string                    | No       | Subject. Defaults to "Re: …" / "Fwd: …" for replies and forwards                     |
| `body`              | string                    | Yes      | Plain-text body. For replies/forwards the original is quoted below it automatically  |
| `reply_to_email_id` | string                    | No       | Reply to this email (sender is added as recipient, threading kept)                   |
| `reply_all`         | boolean                   | No       | With reply_to_email_id: also include the original To and Cc. Default `false`.        |
| `forward_email_id`  | string                    | No       | Forward this email, including its attachments                                        |
| `attachments`       | array of object           | No       | Files to attach: email_id + attachment index from an email, or name + base64 content |
| `confirm`           | boolean                   | Yes      | Must be true: the user has seen this exact email and explicitly approved sending it  |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/send_email \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account": "ACCOUNT_ID", "body": "…", "confirm": true}'
```

## organize_emails

**Archive, label or mark emails** · Change

Changes up to 100 emails at once: mark read or unread, flag or unflag, add or remove labels (Gmail labels, Outlook categories), and move them (move_to: "archive", "trash", "inbox", "junk" or a folder from list_folders). Use ids from search_emails. Before moving to trash, or changing more than 10 emails, say what will happen and get a yes first.

> [!NOTE]
> This changes the emails (marks, labels, moves) but sends nothing. It needs no `confirm`. It stops only while email changes, or all changes, are paused on the **Permissions** page.

| Argument        | Type            | Required | What it is                                                              |
| --------------- | --------------- | -------- | ----------------------------------------------------------------------- |
| `account`       | string          | Yes      | Account id from list_accounts                                           |
| `email_ids`     | array of string | Yes      | Email ids from search_emails or get_thread                              |
| `read`          | boolean         | No       | true = mark read, false = mark unread                                   |
| `flagged`       | boolean         | No       | true = flag/star, false = remove the flag                               |
| `add_labels`    | array of string | No       | Gmail labels or Outlook categories to add (created if new)              |
| `remove_labels` | array of string | No       | Labels or folders to remove                                             |
| `move_to`       | string          | No       | "archive", "trash", "inbox", "junk", or a folder path from list_folders |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/organize_emails \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account": "ACCOUNT_ID", "email_ids": []}'
```

## send_draft

**Send a draft** · Change

Sends an existing draft (from create_draft, or found in the drafts folder) and removes it from Drafts. Read it with get_email first.

> [!IMPORTANT]
> This tool makes a change, so the request must include `"confirm": true`, and changes must be allowed. See [Making changes](https://docs.plugsight.app/developers/calling-tools.md#making-changes).

| Argument   | Type    | Required | What it is                                                                          |
| ---------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `account`  | string  | Yes      | Account id from list_accounts                                                       |
| `draft_id` | string  | Yes      | Email id of the draft                                                               |
| `confirm`  | boolean | Yes      | Must be true: the user has seen this exact draft and explicitly approved sending it |

Example request:

```bash
curl -X POST https://app.plugsight.app/v1/tools/send_draft \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account": "ACCOUNT_ID", "draft_id": "…", "confirm": true}'
```

## Related articles

- [Calling tools](https://docs.plugsight.app/developers/calling-tools.md)
- [Errors](https://docs.plugsight.app/developers/errors.md)
- [Authentication](https://docs.plugsight.app/developers/authentication.md)

---

Web version: https://docs.plugsight.app/developers/email-tools
