Introduction

The DeepSeek Harness (DSH) plugin ecosystem allows developers to extend agent capabilities. When building an agent that needs to read emails, integrating the IMAP protocol directly requires handling details such as connections, authentication, proxying, and error handling. The dsh-email-reader plugin encapsulates this low-level logic and provides the ability to list, read, and search emails.

This plugin mainly addresses two specific issues: first, for Outlook.com accounts where Microsoft has supported only OAuth2 since September 2024, it provides an OAuth2 authentication solution with automatic token refresh; second, it uses tool naming isolation to avoid functional conflicts with the marketplace dsh-email plugin.

Core Features

Built on imapflow, the plugin provides the following tools for DSH models:

  1. ol_email_list: Lists the latest emails in the inbox and returns the sender, subject, time, and flags.
  2. ol_email_read: Reads the full content of a single email and automatically parses the MIME format.
  3. ol_email_search: Performs IMAP full-text search on the server, with results sorted by newest first.

In addition, the plugin supports multi-account configuration, automatic OAuth2 token refresh, HTTP/SOCKS proxying, and standardizing all tool error returns into the { ok, ... } format to prevent exceptions from interrupting the host service.

Installation

Run the following command in a DSH environment to install the plugin:

dsh plugin --profile web add dsh-email-reader

Configuration

The plugin supports three configuration methods: OAuth2 (recommended), password/app-specific password, and environment variables. The following are common configuration examples.

OAuth2 Configuration (Outlook, etc.)

For accounts where only OAuth2 has been supported by Microsoft since September 2024, you must provide refreshToken and clientId.

- insert:
    - id: email-reader
      name: dsh-email-reader
      config:
        accounts:
          - id: outlook
            host: outlook.office365.com
            port: 993
            user: you@outlook.com
            refreshToken: "从 OAuth 授权流程获取"
            clientId: "你的应用 Client ID"
            tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token"
            mailbox: INBOX

Proxy Configuration (Accessing Gmail)

When your network environment requires a proxy (for example, accessing Google from a campus network), you can specify proxy in the account configuration.

- insert:
    - id: email-reader
      name: dsh-email-reader
      config:
        accounts:
          - id: gmail
            host: imap.gmail.com
            port: 993
            user: you@gmail.com
            pass: your-app-password
            proxy: "http://127.0.0.1:7892"
            mailbox: INBOX

Environment Variable Configuration

If you prefer not to store credentials on disk, you can use environment variables. The main variables include DSH_IMAP_HOST, DSH_IMAP_USER, DSH_IMAP_PASS, DSH_IMAP_OAUTH_REFRESH, DSH_IMAP_CLIENT_ID, and DSH_IMAP_PROXY.

Usage Examples

The tool names provided by the plugin all start with ol_email_ to distinguish them from other marketplace plugins.

  1. List emails: Call ol_email_list.
    • Prompt: “Show me the latest 5 emails in my inbox”
  2. Read an email: Call ol_email_read.
    • Prompt: “Read the content of email #12”
  3. Search emails: Call ol_email_search.
    • Prompt: “Search for emails with ‘invoice’ in the subject”

Notes

  1. Microsoft Account Changes: Since September 2024, Microsoft has stopped supporting IMAP basic authentication (username + password) for personal Outlook.com accounts and now supports only OAuth2. For such accounts, OAuth2 must be configured.
  2. Tool Naming Conflicts: To coexist with the marketplace dsh-email plugin, this plugin registers tools with the ol_email_* prefix (ol = Outlook).
  3. Error Handling: All tools return the { ok, ... } format and never throw exceptions, ensuring that configuration errors do not crash the host application.
  4. Permissions and Security: The plugin runs with the permissions of the current DSH process. When configuring credentials (especially passwords and tokens), pay attention to the host’s security policy.

Summary

dsh-email-reader provides IMAP-based email reading capabilities, focusing on resolving the OAuth2 authentication issue for Microsoft accounts and ensuring ecosystem compatibility through namespace isolation. For developers who need to integrate email-processing capabilities into agents, this is an immediately usable solution.

Repository: https://github.com/huaxiren6/dsh-email-reader