email-imap-smtp
Public
README.md
README.md
A hardened fork of altra/email for searching and reading email over IMAP, with optional SMTP sending and move-to-Trash tools.
email_search failures when ImapFlow returns false instead of a UID array.2026-08-01, yesterday, 2 weeks ago, and last 3 months.email_send and email_delete unavailable unless explicitly enabled in settings.Read-only tools are always available after an account is configured:
| Tool | Purpose |
|---|---|
email_accounts | List accounts and exposed capabilities |
email_list | List recent messages from a folder |
email_search | Search by text, sender, recipient, subject, date, or unread state |
email_read | Read one message by UID |
email_list_folders | Discover exact mailbox folder names |
Write tools are disabled by default:
| Tool | Setting required | Effect |
|---|---|---|
email_send | Expose email_send | Sends a plain-text message over SMTP |
email_delete | Expose email_delete | Moves selected UIDs to Trash; it does not permanently erase them |
Enabling a write tool exposes it to the active model. Configure LM Studio to ask for tool-call approval, and inspect the final arguments before approving.
From LM Studio Hub, use Run in LM Studio. For local development:
npm run check runs unit tests, builds the plugin, and runs the unit tests again to detect generated-test regressions.
Up to three accounts are supported. A slot is active when IMAP host, username, and password are all populated.
| Setting | Typical Gmail value |
|---|---|
| IMAP host | imap.gmail.com |
| IMAP port | 993 |
| SMTP host | smtp.gmail.com |
| SMTP port | 587 |
| Username | Full email address |
| Password | Provider-issued app password |
SMTP host may be left blank for a read-only account. email_send additionally requires the global plugin toggle Expose email_send.
Enable two-step verification and create a Google app password for the plugin. Use the app password, not the normal Google account password.
This fork currently implements username/password IMAP and SMTP authentication, not OAuth2. Microsoft tenants that disable basic authentication will not work. Do not advertise universal Microsoft 365 compatibility until OAuth2 is implemented and tested.
Use the provider's documented IMAP/SMTP hosts, ports, and app-password requirements. Some providers disable IMAP or SMTP by default or require a paid plan.
since is inclusive and before is exclusive. To search one exact day, use the next day as the upper bound:
Accepted forms:
Calendar months and years are shifted as calendar units and clamp at month-end. For example, one month before March 31 becomes February 28 or 29.
This plugin has direct access to configured mailboxes. The primary risks are credential exposure, model mistakes, prompt injection in email content, accidental sending, and accidental Trash operations.
Controls included here:
These controls reduce risk; they do not make arbitrary models trustworthy. Use a dedicated app password, keep write tools disabled when unnecessary, and review tool calls in LM Studio.
Unit tests require no mailbox credentials:
The original Ethereal SMTP tests are retained as optional network integration tests:
They require internet access and can fail due to external service availability even when the plugin code is correct.
LM Studio loads the generated root-level JavaScript files. Source tests remain under src/__tests__ and are excluded from TypeScript emission.
Set your own Hub username or organization in manifest.json, use a unique kebab-case plugin name, then:
See RELEASE.md for the full checklist.
This repository contains upstream-derived material from the public LM Studio
Hub artifact altra/email and original contributions by lhzawk.
The original contributions are available under the MIT License. The
upstream-derived material remains subject to the LM Studio Hub Public Content
license. See LICENSE.md and NOTICE.md for details.
A hardened fork of altra/email for searching and reading email over IMAP, with optional SMTP sending and move-to-Trash tools.
email_search failures when ImapFlow returns false instead of a UID array.2026-08-01, yesterday, 2 weeks ago, and last 3 months.email_send and email_delete unavailable unless explicitly enabled in settings.Read-only tools are always available after an account is configured:
| Tool | Purpose |
|---|---|
email_accounts | List accounts and exposed capabilities |
email_list | List recent messages from a folder |
email_search | Search by text, sender, recipient, subject, date, or unread state |
email_read | Read one message by UID |
email_list_folders | Discover exact mailbox folder names |
Write tools are disabled by default:
| Tool | Setting required | Effect |
|---|---|---|
email_send | Expose email_send | Sends a plain-text message over SMTP |
email_delete | Expose email_delete | Moves selected UIDs to Trash; it does not permanently erase them |
Enabling a write tool exposes it to the active model. Configure LM Studio to ask for tool-call approval, and inspect the final arguments before approving.
From LM Studio Hub, use Run in LM Studio. For local development:
npm run check runs unit tests, builds the plugin, and runs the unit tests again to detect generated-test regressions.
Up to three accounts are supported. A slot is active when IMAP host, username, and password are all populated.
| Setting | Typical Gmail value |
|---|---|
| IMAP host | imap.gmail.com |
| IMAP port | 993 |
| SMTP host | smtp.gmail.com |
| SMTP port | 587 |
| Username | Full email address |
| Password | Provider-issued app password |
SMTP host may be left blank for a read-only account. email_send additionally requires the global plugin toggle Expose email_send.
Enable two-step verification and create a Google app password for the plugin. Use the app password, not the normal Google account password.
This fork currently implements username/password IMAP and SMTP authentication, not OAuth2. Microsoft tenants that disable basic authentication will not work. Do not advertise universal Microsoft 365 compatibility until OAuth2 is implemented and tested.
Use the provider's documented IMAP/SMTP hosts, ports, and app-password requirements. Some providers disable IMAP or SMTP by default or require a paid plan.
since is inclusive and before is exclusive. To search one exact day, use the next day as the upper bound:
Accepted forms:
Calendar months and years are shifted as calendar units and clamp at month-end. For example, one month before March 31 becomes February 28 or 29.
This plugin has direct access to configured mailboxes. The primary risks are credential exposure, model mistakes, prompt injection in email content, accidental sending, and accidental Trash operations.
Controls included here:
These controls reduce risk; they do not make arbitrary models trustworthy. Use a dedicated app password, keep write tools disabled when unnecessary, and review tool calls in LM Studio.
Unit tests require no mailbox credentials:
The original Ethereal SMTP tests are retained as optional network integration tests:
They require internet access and can fail due to external service availability even when the plugin code is correct.
LM Studio loads the generated root-level JavaScript files. Source tests remain under src/__tests__ and are excluded from TypeScript emission.
Set your own Hub username or organization in manifest.json, use a unique kebab-case plugin name, then:
See RELEASE.md for the full checklist.
This repository contains upstream-derived material from the public LM Studio
Hub artifact altra/email and original contributions by lhzawk.
The original contributions are available under the MIT License. The
upstream-derived material remains subject to the LM Studio Hub Public Content
license. See LICENSE.md and NOTICE.md for details.
npm install
npm run check
lms dev
since="2026-08-01", before="2026-08-02"
2026-08-01
today
yesterday
tomorrow
2 days ago
2 weeks ago
a month ago
last week
last 3 months
npm test
npm run test:integration
npm run build
lms login
npm run check
lms push --write-revision
npm install
npm run check
lms dev
since="2026-08-01", before="2026-08-02"
2026-08-01
today
yesterday
tomorrow
2 days ago
2 weeks ago
a month ago
last week
last 3 months
npm test
npm run test:integration
npm run build
lms login
npm run check
lms push --write-revision