Lessie Email — Multi-Provider Email Management

Setup

Add the Lessie Email MCP server to your MCP config (Claude Code ~/.claude.json, Cursor ~/.cursor/mcp.json, Codex ~/.codex/config.toml, etc.):

{
  "mcpServers": {
    "lessie-email-mcp": {
      "command": "npx",
      "args": ["-y", "@lessie/mcp-server"],
      "env": {
        "LESSIE_REMOTE_MCP_URL": "https://app.lessie.ai/email-api/mcp-public/mcp"
      }
    }
  }
}

Uninstall

Remove the "lessie-email" entry from your MCP config and run rm -rf ~/.lessie/.

Version check

Run this check once at the start of each session. Non-blocking — if any command fails, skip silently.

Read current local version from this file's metadata version field above.

Fetch remote version:

curl -sf --max-time 5 https://raw.githubusercontent.com/LessieAI/lessie-skill/main/lessie-email/SKILL.md | head -5 | grep 'version:' | head -1 | awk '{print $2}'

If the remote version is newer → tell the user:
⬆️ A newer version of lessie-email skill is available ({current} → {remote}). Run this command to update:
```
npx skills add LessieAI/lessie-skill -y -g
```
If versions match or check fails → skip, say nothing.

Authorization

Directly call use_lessie to perform the desired action — skip authorization if already connected.
If use_lessie fails (e.g., returns "not authorized" or "remote MCP server not connected") → call authorize to start the OAuth flow:
- authorize returns an authorization URL. Tell the user you need to open a browser for Lessie login/registration, and open it using the appropriate system command:
  - macOS: open "<url>"
  - Linux: xdg-open "<url>"
  - Windows: start "<url>"
- Tell the user the browser has been opened and they need to complete login/registration.
- After the user confirms, call authorize again to verify the connection.
- If authorization fails (timeout, denied, port conflict), follow the diagnostic hints returned by authorize and retry.
After authorization succeeds → retry the original use_lessie call.

Troubleshooting: Authorization repeatedly fails

Root cause: stale lessie-mcp-server processes from old sessions occupy the callback port (19836), forcing port fallback and corrupting OAuth client state.

Fix — kill stale processes and clear storage, then re-authorize:

ps aux | grep 'lessie-mcp-server' | grep -v grep | awk '{print $2}' | xargs kill 2>/dev/null
rm -rf ~/.lessie/
lsof -i :19836 | grep LISTEN  # should return nothing

Always inform the user before opening the browser — never silently redirect.

Quick start

After setup, try:

"Show me my email accounts and unread counts"
"Send an email from alice@company.com to bob@example.com about the Q2 report"
"List my recent email threads"
"Create a bulk email campaign to these 50 contacts"
"Draft an email to the engineering team about the sprint review"
"Mark all emails in this thread as read"

Tools overview

Email Accounts

Tool	When to use
`list_email_accounts_with_unread`	View all linked email accounts with unread counts

Email Operations

Tool	When to use
`send_email`	Send an email (supports HTML, CC/BCC, attachments, replies)
`get_email_detail`	View full email details (content, delivery status, read status)
`list_sent_emails`	Browse sent emails with cursor pagination
`get_email_quota`	Check daily sending quota for a specific email address
`delete_email`	Soft-delete an email
`set_email_read_status`	Mark an email as read or unread

Thread Management

Tool	When to use
`list_threads`	Browse email conversations (all/read/unread filtering)
`get_thread_messages`	View all messages in a conversation thread
`delete_thread`	Soft-delete an entire conversation thread
`set_thread_read_status`	Mark all emails in a thread as read or unread

Drafts

Tool	When to use
`create_draft`	Create a new email draft
`update_draft`	Update an existing draft (subject, content, recipients, etc.)
`delete_draft`	Delete a draft
`list_drafts`	Browse drafts with cursor pagination

Bulk Email Tasks

Tool	When to use
`create_task`	Create a bulk email send task (auto-schedules per recipient)
`list_tasks`	Browse bulk tasks with progress info
`get_task_detail`	View task details with delivery/open/fail stats per recipient
`delete_task`	Delete a bulk email task
`pause_task`	Pause a running bulk email task
`resume_task`	Resume a paused bulk email task

Agent behavior rules

Before sending emails

Always check accounts first: Call list_email_accounts_with_unread to get available sender addresses.
No email accounts bound: If the account list is empty, tell the user they have no email accounts linked yet and guide them to visit https://app.lessie.ai/ to bind an email account. Open the URL using the appropriate system command:
- macOS: open "https://app.lessie.ai/"
- Linux: xdg-open "https://app.lessie.ai/"
- Windows: start "https://app.lessie.ai/" Then ask the user to return after binding and retry.
Always check quota: Call get_email_quota for the chosen sender to confirm quota is sufficient.
Never guess email addresses: Only use addresses returned by the account list.

Replying to emails

Get the thread context: call get_thread_messages to see the conversation.
Use the thread_id and reply_to_message_id from the last message.
Pass both when calling send_email for a proper threaded reply.

Draft workflow

Create a draft with create_draft — specify sender, recipients, subject, and content.
Update the draft with update_draft if changes are needed.
When ready, use send_email with the finalized content (drafts are not sent directly).
Delete the draft with delete_draft after sending or if no longer needed.

Bulk task management

After creating a task with create_task, monitor progress with get_task_detail.
Use pause_task to temporarily halt a running campaign (e.g., if issues are found).
Use resume_task to continue a paused campaign.
Use delete_task to permanently remove a task.

Gmail/Outlook specific

When calling get_email_detail, delete_email, get_thread_messages for Gmail/Outlook accounts, always pass the email parameter.
The system auto-routes to the correct provider API based on the email address.

Key constraints

Cursor pagination: all list endpoints use cursor + size — pass next_cursor from previous response.
Default page size: 20 (max 100).
Email content: provide at least text_content or html_content — if only text is provided, HTML is auto-generated.
Attachments require pre-uploaded S3 keys with s3key, filename, mime_type, size.
Bulk tasks auto-schedule sends across time to respect quotas and avoid spam.

lessie-email