PlugsightDocs

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}'