LocalHero Org

Helping Organisations get organised!

Abilities

Part of LH Email

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 Default 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 Default 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 Default 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 Default 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 Default 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 Default 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 Default 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 Default 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 Default 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.

If you like this plugin please consider making a donation to further development