Lessie email

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.

1. Read current local version from this file's metadata version field above.
2. 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}'
   

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

4. If versions match or check fails → skip, say nothing.

Authorization

1. Directly call use_lessie to perform the desired action — skip authorization if already connected.
2. 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.
3. 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 [email protected] to [email protected] 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

1. Always check accounts first: Call list_email_accounts_with_unread to get available sender addresses.
2. 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.
3. Always check quota: Call get_email_quota for the chosen sender to confirm quota is sufficient.
4. Never guess email addresses: Only use addresses returned by the account list.

Replying to emails

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

Draft workflow

1. Create a draft with create_draft — specify sender, recipients, subject, and content.
2. Update the draft with update_draft if changes are needed.
3. When ready, use send_email with the finalized content (drafts are not sent directly).
4. 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.