Skip to content

feat: add AgentMail as alternative email provider#49

Open
adi-singh13 wants to merge 1 commit into
codefuturist:mainfrom
adi-singh13:feat/agentmail-provider
Open

feat: add AgentMail as alternative email provider#49
adi-singh13 wants to merge 1 commit into
codefuturist:mainfrom
adi-singh13:feat/agentmail-provider

Conversation

@adi-singh13

Copy link
Copy Markdown

Summary

This PR adds AgentMail as an optional email provider alongside the existing IMAP/SMTP support. The integration is fully additive — no existing code is modified or removed.

Motivation

While IMAP/SMTP is the standard for email access, some users (especially those building AI agents) prefer a simpler setup that does not require configuring mail server hosts, ports, TLS, and credentials. AgentMail offers:

  • API key auth only — no IMAP/SMTP server configuration needed
  • Programmatic inbox creation — spin up new email addresses on the fly
  • extracted_text — automatically strips quoted reply chains, useful for AI processing
  • Simple REST API — no connection pooling, IDLE management, or reconnection logic

This makes it a natural fit as an alternative provider for an email MCP server.

What changed

New files

  • src/services/agentmail.service.ts — Lightweight AgentMail API client (uses fetch, no additional npm dependencies)
  • src/tools/agentmail.tool.ts — 5 MCP tools prefixed with agentmail_ to avoid name collisions

Modified files

  • src/config/schema.ts — Optional [agentmail] config section with Zod validation
  • src/config/loader.ts — Parse AgentMail config from TOML, updated config template
  • src/types/index.tsAgentMailConfig interface
  • src/tools/register.ts — Conditionally register AgentMail tools when configured
  • src/main.ts — Instantiate AgentMailService when API key is present (config or AGENTMAIL_API_KEY env var)
  • README.md — Document setup, configuration, and available tools

New tools

Tool Description
agentmail_create_inbox Create a new inbox with a unique @agentmail.to address
agentmail_list_inboxes List all inboxes for the API key
agentmail_list_messages List messages in an inbox
agentmail_get_message Get full message content
agentmail_send_message Send email from an inbox

Configuration

Via config.toml:

[agentmail]
api_key = "your-api-key"

Or environment variable:

AGENTMAIL_API_KEY=your-api-key

Both IMAP/SMTP accounts and AgentMail can be used simultaneously — the config schema now requires at least one IMAP/SMTP account or an [agentmail] section.

Design decisions

  • No new npm dependencies — the service uses native fetch to call the AgentMail REST API, avoiding any build-time dependency
  • Tool name prefix — all tools use agentmail_ prefix so they coexist cleanly with existing tools
  • Follows existing patterns — service/tool separation matches the codebase architecture (business logic in services, MCP wiring in tools)
  • Additive only — existing IMAP/SMTP functionality is completely unchanged

Add AgentMail (https://agentmail.to) as an optional email provider
alongside the existing IMAP/SMTP support. This gives users a simpler
setup path — just an API key instead of configuring mail server hosts,
ports, TLS settings, and credentials.

New files:
- src/services/agentmail.service.ts — AgentMail API client service
- src/tools/agentmail.tool.ts — MCP tools for AgentMail operations

Modified files:
- src/config/schema.ts — Add optional [agentmail] config section
- src/config/loader.ts — Parse agentmail config, update template
- src/types/index.ts — Add AgentMailConfig type
- src/tools/register.ts — Wire up AgentMail tools when configured
- src/main.ts — Instantiate AgentMailService when API key is present
- README.md — Document AgentMail setup and available tools

The integration is fully additive — no existing IMAP/SMTP code is
changed. AgentMail tools are prefixed with agentmail_ to avoid
name collisions. Configuration can be done via config.toml or the
AGENTMAIL_API_KEY environment variable.
@adi-singh13 adi-singh13 requested a review from codefuturist as a code owner May 25, 2026 22:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant