Abilities

copy-imap-attachment Copy IMAP Attachment
create-draft Create Email Draft
create-reply-draft Create Email Reply Draft
get-compose Get Compose Email
get-imap-headers Get IMAP Headers
get-imap-message Get IMAP Message
get-imap-quota Get IMAP Quota
list-composes List Compose Emails
list-imap-connections List IMAP Connections
list-imap-folders List IMAP Folders
list-imap-messages List IMAP Messages
search-imap-messages Search IMAP Messages
search-messages Search Sent Messages
update-draft Update Email Draft

Copy IMAP Attachment

lh-email/copy-imap-attachment Idempotent

Copies a single IMAP attachment out of the mailbox onto this server, server-side, so the file never passes through the response, and returns a source reference that every lh-mcp-file-abilities ability accepts as its source input: follow with get-file-text, describe-file, get-file-rows or get-file-image to read it. destination chooses where the copy goes. private (the default) files it into this site's media library through LH Private Uploads: the file is written straight into its private directory and served only through the access-checked proxy URL, and the copy is refused if LH Private Uploads is not active. media files it into normal public uploads; a copy attached to a private parent still ends up private, and is_private reports what actually happened. Both check the file type as the normal uploader does, refuse anything WordPress would refuse, and are idempotent: the origin (connection, folder, UID, part, Message-ID, sender, date, subject) is recorded in attachment meta, and a repeat call for the same message and part returns the existing attachment with newly_saved false. sandbox writes the file to your own lh-mcp-sandbox directory under lh-email/, for reading a document without keeping it: no attachment is created, the copy counts against your sandbox quota, a repeat call replaces it, and you remove it with lh-mcp-sandbox/delete-staged-path once read. Attachments over the configured limit (default 5MB) are refused rather than truncated. The message is not marked as seen. Use the part number from get-imap-message's attachment list. Requires edit_posts, plus upload_files for private and media, or the lh-mcp-sandbox capability (install_plugins by default) for sandbox.

Parameter	Type	Required	Default	Description
`slug`	string	Yes		IMAP connection slug.
`folder`	string	Yes		Folder name.
`uid`	integer	Yes		Message UID.
`part`	integer	Yes		Attachment part number, as returned in the part field of get-imap-message's attachment list (1-based).
`destination`	string	No	`"private"`	private (default): a private media attachment. media: a public media attachment. sandbox: a file in your own lh-mcp-sandbox directory, for reading without keeping. One of: `private`, `media`, `sandbox`.
`title`	string	No		Attachment title, for private and media. Optional – defaults to the file name without its extension.
`parent_id`	integer	No		ID of a post to attach the file to, for private and media. Optional. You must be able to edit it.

Create Email Draft

lh-email/create-draft

Creates a new lh_email_compose post as a draft. Cannot publish or dispatch — use the WordPress editor to send when ready. Requires edit_posts.

Parameter	Type	Required	Description
`subject`	string	Yes	Email subject line.
`body`	string	No	Email body as HTML or plain text. Will be stored as `post_content` (raw block markup is also accepted).
`mode`	string	No	Compose mode: single (one message, multiple recipients share the same body) or broadcast (one personalised message per recipient). Defaults to single. One of: `single`, `broadcast`.
`to`	string	No	Comma-separated To email addresses.
`cc`	string	No	Comma-separated CC email addresses. Optional.
`bcc`	string	No	Comma-separated BCC email addresses. Optional.

Create Email Reply Draft

lh-email/create-reply-draft

Creates a new lh_email_compose post as a draft that threads into an existing email conversation via In-Reply-To/References headers. Fetches the source message internally via its IMAP UID to auto-populate the subject and threading headers — the source message must be real; there is no way to fabricate threading against a message that does not exist. Single mode only, with no mode param — a reply targets exactly one prior message, which does not fit broadcast's one-personalised-message-per-recipient model. Cannot publish or dispatch — use the WordPress editor to send when ready. Requires edit_posts.

Parameter	Type	Required	Description
`reply_to_imap_uid`	integer	Yes	UID of the IMAP message being replied to, as returned by get-imap-message, search-imap-messages, or list-imap-messages.
`slug`	string	Yes	IMAP connection slug the source message lives on.
`folder`	string	Yes	IMAP folder the source message lives in.
`body`	string	No	Reply body as HTML or plain text. Will be stored as `post_content`. This is the primary reply content — individually-worded per recipient is left to the caller, not templated here.
`to`	string	No	Comma-separated To email addresses. Optional — defaults to the source message's sender.
`cc`	string	No	Comma-separated CC email addresses. Optional.
`bcc`	string	No	Comma-separated BCC email addresses. Optional.
`quote_original`	boolean	No	Whether to append a quoted "On {date}, {sender} wrote:" block with the original message below the reply body. Defaults to false so the reply text stays the primary content.

Get Compose Email

lh-email/get-compose Read-only Idempotent

Retrieves a compose email post by ID. Returns subject, mode, envelope fields, status, raw post_content, rendered body HTML, and dispatch meta. Useful for reading sent emails as templates. Requires edit_posts.

Parameter	Type	Required	Default	Description
`post_id`	integer	Yes		ID of the `lh_email_compose` post to retrieve.

Get IMAP Headers

lh-email/get-imap-headers Read-only Idempotent

Fetches headers only for a single IMAP message by UID — no body fetch. Useful for quick threading lookups. Includes sent_match check against the outbound email log. Read-only — does not mark as seen. Requires edit_posts.

Parameter	Type	Required	Description
`slug`	string	Yes	IMAP connection slug.
`folder`	string	Yes	Folder name.
`uid`	integer	Yes	Message UID.

Get IMAP Message

lh-email/get-imap-message Read-only Idempotent

Fetches a single IMAP message by UID. Returns full headers, plain text body, HTML body, attachment list (metadata only, no content — pass an attachment's part number to copy-imap-attachment to copy it onto the server, then read it with the lh-mcp-file-abilities abilities), In-Reply-To, References, and a sent_match if the message is a reply to a record in the outbound email log. Read-only — does not mark as seen. Requires edit_posts.

Parameter	Type	Required	Description
`slug`	string	Yes	IMAP connection slug.
`folder`	string	Yes	Folder name.
`uid`	integer	Yes	Message UID.

Get IMAP Quota

lh-email/get-imap-quota Read-only Idempotent

Returns mailbox quota and usage if the IMAP server supports it (QUOTAROOT). Fails with a message when the server does not report a quota. Requires edit_posts.

Parameter	Type	Required	Default	Description
`slug`	string	Yes		IMAP connection slug.

List Compose Emails

lh-email/list-composes Read-only Idempotent

Lists compose email posts. Optionally filter by status (draft, publish) and/or mode (single, broadcast). Supports keyword search on subject and pagination. Sent emails are useful as templates for new compositions. Requires edit_posts.

Parameter	Type	Required	Description
`status`	string	No	Filter by post status: draft, publish, or any (default: any). One of: `draft`, `publish`, `any`.
`mode`	string	No	Filter by compose mode: single or broadcast. Optional — omit for all modes. One of: `single`, `broadcast`.
`search`	string	No	Keyword to search in the subject (post title). Optional.
`per_page`	integer	No	Results per page. Default 20, max 100.
`page`	integer	No	Page number. Default 1.

List IMAP Connections

lh-email/list-imap-connections Read-only Idempotent

Lists all configured IMAP connections for the current site. Returns slug, label, host and port for each, never credentials, plus whether IMAP is available on this server. Use a slug from here with the other IMAP abilities. Requires edit_posts.

Parameter	Type	Required	Default	Description
`_`	string	No	`""`	Unused; takes no input.

List IMAP Folders

lh-email/list-imap-folders Read-only Idempotent

Lists all folders/mailboxes available on an IMAP connection, sorted by path. Requires edit_posts.

Parameter	Type	Required	Default	Description
`slug`	string	Yes		IMAP connection slug.

List IMAP Messages

lh-email/list-imap-messages Read-only Idempotent

Lists messages in an IMAP folder with sorting and pagination. Returns message summaries including unseen status. Sorting by date is done by the server across the whole folder; sorting by from, subject or size only orders the page that was fetched. Read-only — does not mark messages as seen. Requires edit_posts.

Parameter	Type	Required	Description
`slug`	string	Yes	IMAP connection slug.
`folder`	string	No	Folder name. Default: INBOX.
`limit`	integer	No	Messages per page. Default 20, max 100.
`page`	integer	No	Page number. Default 1.
`sort`	string	No	Sort field: date, from, subject, size. Default: date. One of: `date`, `from`, `subject`, `size`.
`order`	string	No	Sort order: asc or desc. Default: desc. One of: `asc`, `desc`.

Search IMAP Messages

lh-email/search-imap-messages Read-only Idempotent

Search messages using IMAP search criteria or Gmail search syntax. Standard IMAP examples: FROM "peter@", SINCE "1-Jan-2026", SUBJECT "invoice", UNSEEN, ALL. Gmail: pass gmail_search for full Gmail search syntax. Read-only — does not mark messages as seen. Requires edit_posts.

Parameter	Type	Required	Description
`slug`	string	Yes	IMAP connection slug.
`folder`	string	No	Folder name. Default: INBOX.
`query`	string	No	Standard IMAP search string. Default: ALL.
`gmail_search`	string	No	Gmail search query (only used when host is imap.gmail.com). Overrides query.
`limit`	integer	No	Results per page. Default 20, max 100.
`page`	integer	No	Page number. Default 1.

Search Sent Messages

lh-email/search-messages Read-only Idempotent

Searches the lh_email_messages table for this site. Supports filtering by subject keyword, recipient email, and delivery status. Results are scoped to the current site_id. Requires install_plugins.

Parameter	Type	Required	Description
`search`	string	No	Keyword to search in the subject field. Optional.
`email`	string	No	Filter by recipient email address (exact match against actors table). Optional.
`status`	string	No	Filter by delivery status: `lh_email_queued`, `lh_email_sending`, `lh_email_sent`, `lh_email_failed`, `lh_email_skipped`. Optional. One of: `lh_email_queued`, `lh_email_sending`, `lh_email_sent`, `lh_email_failed`, `lh_email_skipped`.
`per_page`	integer	No	Results per page. Default 20, max 100.
`page`	integer	No	Page number. Default 1.

Update Email Draft

lh-email/update-draft Destructive Idempotent

Updates an existing lh_email_compose draft. Patch semantics — only supplied fields are changed, and each supplied field replaces the stored value. Refuses if the compose post has already been dispatched. Requires edit_posts.

Parameter	Type	Required	Description
`post_id`	integer	Yes	ID of the `lh_email_compose` draft to update.
`subject`	string	No	New subject line. Optional — omit to keep existing.
`body`	string	No	New body content. Optional — omit to keep existing.
`mode`	string	No	Compose mode: single or broadcast. Optional — omit to keep existing. One of: `single`, `broadcast`.
`to`	string	No	Comma-separated To addresses. Optional — omit to keep existing.
`cc`	string	No	Comma-separated CC addresses. Optional — omit to keep existing.
`bcc`	string	No	Comma-separated BCC addresses. Optional — omit to keep existing.