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 for the request and response format.
| Tool | What it does | Kind |
|---|---|---|
list_folders |
List folders | Read |
search_emails |
Search / list emails | Read |
get_email |
Read an email | Read |
get_thread |
Read a conversation | Read |
get_attachment |
Read an attachment | Read |
create_draft |
Create a draft | Change |
send_email |
Send an email | Change |
organize_emails |
Archive, label or mark emails | Change |
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.
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:
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.
| 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. |
Example request:
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:
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:
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:
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.
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:
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.
This tool makes a change, so the request must include
"confirm": true, and changes must be allowed. See 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:
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.
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:
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.
This tool makes a change, so the request must include
"confirm": true, and changes must be allowed. See 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:
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}'