Introduction

Integrating an email tool into DSH, if you only want the agent to “be able to send emails,” you usually only need to register a few sending and querying interfaces. However, in actual email usage, the problems go beyond just sending: incoming emails need to enter the agent’s context, failed sends need to be known, outbound emails require human confirmation and recipient restrictions, and cross-session follow-ups cannot be lost just because a single conversation has ended.

dsh-agentmail is a DSH plugin. Its positioning is to provide a mailbox for DeepSeek Harness agents and bind incoming emails to sessions distinguished by email threads. The public repository address is:

https://github.com/agentmail-to/dsh-agentmail

The license is MIT.

What is it

The core capabilities of dsh-agentmail can be summarized as:

  • Provide tools for sending, reading, and searching emails;
  • Bind incoming emails to the agent and to a session corresponding to an email thread;
  • Report back on email bounces to avoid treating failed sends as delivered;
  • Outbound sending has an approval gate and recipient allowlist;
  • Follow-up tasks can survive across sessions, handled via due-date labels and periodic sweeps;
  • Inject inbox identity and untrusted-content rules into the system prompt.

It is not just an email API wrapper, but a combination of email threads, DSH sessions, approval, and untrusted input processing.

Tool List

The plugin provides 11 curated tools:

agentmail_list_inboxes
agentmail_create_inbox
agentmail_list_threads
agentmail_get_thread
agentmail_search
agentmail_send_message
agentmail_reply
agentmail_create_draft
agentmail_send_draft
agentmail_update_labels
agentmail_followup

These tools cover common email workflows such as mailboxes, threads, messages, drafts, labels, and follow-ups.

Installation and Enabling

Plugin Method

First set the AgentMail API key, then install the plugin:

export AGENTMAIL_API_KEY=...
dsh plugin --profile demo add dsh-agentmail
dsh --profile demo

Here the demo profile is used. If your DSH environment uses a different profile, you need to replace it according to the actual environment.

Using MCP Client Only

If you only need to access it via an MCP client, you can configure @deepseek-ai/dsh-mcp-client:

- id: mcp-agentmail
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: agentmail
    transport: streamable-http
    url: https://mcp.agentmail.to/mcp
    headers:
      Authorization: 'Bearer ${process.env.AGENTMAIL_API_KEY}'

Please note: The MCP-client path does not provide incoming emails, bounce reports, approvals, follow-ups, or inbox identity rules. It is more suitable as a lightweight tool integration rather than a complete email agent workflow.

Local Development

If you want to build and debug locally, you can execute:

npm install && npm run build
dsh web --patch ./cordis.patch.yml

Thread Binding

A key design of dsh-agentmail is that incoming emails are bound to DSH sessions based on email threads.

For the same email thread, the plugin will reuse the corresponding session rather than creating a new context for every single email. This preserves the context within the thread, preventing the agent from splitting consecutive emails into unrelated independent tasks.

Several related behaviors are worth noting:

  • Concurrent emails in the same thread use an in-flight latch to avoid creating duplicate sessions within the creation window;
  • Idle disposal is non-destructive;
  • maxLive serves only as a flood cap, not as a sequence for complex reasoning;
  • Threads initiated by outbound emails start from the session of the first sent email; subsequent replies seed a new thread session containing only the thread content rebuildable from the API, excluding the private reasoning of the sending session.

If you do not want to split sessions by thread, you can disable threadSessions.enabled to route emails uniformly to fallbackSessionId:

threadSessions:
  enabled: false

Follow-up Mechanism

Ordinary in-session reminders rely on the current session remaining alive. However, email follow-ups often occur in scenarios where “the other party hasn’t replied yet,” at which point the session may have already cooled down.

dsh-agentmail handles this issue through labels. Calling:

agentmail_followup

will write a tag similar to:

dsh-followup-YYYY-MM-DD

to the thread. Subsequently, a periodic sweep will query expiring tags based on followupSweepMs and only wake up the corresponding session.

This means that follow-up status is stored in email thread tags, rather than relying solely on the lifecycle of a single session.

Security and Permissions

dsh-agentmail treats incoming email content as untrusted input.

Each incoming email body will be fenced and marked:

<email-content untrusted="true">
</email-content>

The system prompt also emphasizes that email text within the fence is data, not instructions. Even if the email content claims to be a system message, an admin message, or another high-privilege source, it should not be executed as an instruction.

There are also several layers of restrictions on the outbound side:

  • When readOnly: true, no write tools are registered;
  • allowedRecipients is enforced by ctx.tools.guard() and is a monotonic rejection; subsequent listeners cannot revoke it;
  • requireApprovalForSend is enabled by default and returns ask in tools/pre-execute;
  • wakeIdleAgent is disabled by default; incoming emails append context rather than directly starting a turn.

Together, these rules aim not to make the email tool “smarter,” but to establish clear boundaries for email content, sending actions, and session waking.

Use Cases

dsh-agentmail is suitable for these requirements:

  • Wanting a DSH agent to have independent mailbox capabilities;
  • Needing to preserve context based on email threads;
  • Needing to distinguish incoming content from model instructions;
  • Needing human approval before sending emails externally;
  • Needing to restrict recipients that can be sent to;
  • Needing to persist “follow-up later” out of a single session.

If you are just temporarily calling the email API, the MCP client might be sufficient. If you want the agent to handle incoming, replies, drafts, tags, and follow-ups over the long term, the plugin path is more complete.

Pre-installation Checks

The plugin runs under the permissions of the current DSH process, so it is recommended to check the source code, license, and configuration items before installation. The license for dsh-agentmail is MIT, but this does not mean you can skip local security review.

It is recommended to at least confirm:

  • What tools the plugin registers;
  • Whether allowedRecipients is configured;
  • Whether requireApprovalForSend matches your sending strategy;
  • Whether readOnly: true should be enabled;
  • Whether wakeIdleAgent needs to remain disabled by default;
  • Whether the untrusted-content rules for incoming emails are added to your system prompt configuration.
  • Community Directory: https://www.skillhub.cn/plugins/agentmail-to/dsh-agentmail
  • GitHub: https://github.com/agentmail-to/dsh-agentmail

DSH’s plugin ecosystem emphasizes “everything is a plugin,” and the community directory is also an independent site, not an official app store. The value of dsh-agentmail lies in handling thread binding, failure receipts, outbound approvals, follow-ups, and untrusted input while integrating email capabilities into the DSH agent.