The Problem

Autonomous AI agents need reliable email capabilities without human overhead, but building and operating an email stack from scratch involves CAPTCHAs, verification flows, and ongoing administration. This repository addresses that by providing an email provider purpose-built for agents, with proof-of-work signup to avoid abuse and JMAP for fluent mailbox API access that models already understand well.

What This Does

Atomic Mail Agentic is a portfolio of 4 semi-independent projects rather than a single monorepo. The ts directory (112 files, 103 code files) contains the core TypeScript skill framework with JMAP integration, LangChain tooling, and CLI commands. The integrations directory (205 files) provides adapters for Dify plugins, n8n nodes, and Skill CMS deployments. The py directory (37 files, 30 code files) implements the server and MCP integration in Python. A .vitepress site provides documentation. The service lets agents register @atomicmail.ai inboxes end-to-end, manage mail via JMAP (read/send mail, create drafts, search, manage threads), and onboard via a proof-of-work protocol that provides anti-abuse properties without CAPTCHAs or manual approval.

Key entry points include main at ts/src/mcp/main.ts:57 (reaches 99 functions, called from 1 place), execute at integrations/n8n/atomicmail/nodes/AtomicMail/AtomicMail.node.ts:334 (reaches 100 functions, called by nothing else in the repo), and CLI commands cmdJmapRequest and cmdRegister at ts/src/skill/cli.ts.

How It Is Wired

Execution starts at the MCP main function in ts/src/mcp/main.ts:57, which routes through 99 downstream functions. The N8N node execute at integrations/n8n/atomicmail/nodes/AtomicMail/AtomicMail.node.ts:334 is a terminal entry point reaching 100 functions but called from outside the repository. CLI commands cmdJmapRequest (ts/src/skill/cli.ts:159, reaches 70 functions) and cmdRegister (ts/src/skill/cli.ts:58, reaches 40 functions) each have a single call site within the repo.

The internal call graph shows 446 resolved call edges. optionalTrimmedString is called from 13 places, create from 9, and renderSkillMd from 8. runJmapRequest is called from 8 places. The module ts/src/lib/agent/session/agent-credentials-store.ts is a hub: 13 modules depend on it, giving it high blast radius. Three files participate in circular import dependencies: ts/src/lib/agent/jmap/agent-jmap.ts, agent-jmap-email-charset.ts, and agent-jmap-blob-upload.ts, which must be broken by extracting shared types or inverting a dependency. py/src/atomicmail/jmap_request.py at 793 lines is oversized and should be split by responsibility.

Effects outside the process: main touches the filesystem via Deno.mkdir. The most connected modules are ts/src/lib/mod (Ca 10, Ce 22, instability 0.69) and integrations/skill/atomicmail/lib/esm/lib/mod (Ca 1, Ce 19, instability 0.95).

How To Use It

Setup: The repository uses npm as package manager (package.json at root). Install dependencies with npm install at the root. Docker is supported—docker-compose demo config exists at integrations/n8n/docker-compose.demo.yml. Python dependencies are in integrations/dify/atomicmail/requirements.txt and integrations/n8n/atomicmail/package.json.

Configuration: Environment variables are referenced in integrations/dify/atomicmail/.env.example. The n8n integration has its own .prettierrc.js, package.json, and tsconfig.json. No committed secrets were found, but configure required keys per the integration READMEs.

Running it: To start the MCP server, invoke the entry point at ts/src/mcp/main.ts. For n8n workflow execution, the node at integrations/n8n/atomicmail/nodes/AtomicMail/AtomicMail.node.ts:334 is the starting point. CLI usage is available via ts/src/skill/cli.ts with commands cmdJmapRequest, cmdRegister, and cmdHelp.

Real-World Use

An agent needing to send and read email can register an @atomicmail.ai inbox via the proof-of-work signup flow, then use JMAP operations to manage correspondence. For example, an n8n workflow can call the AtomicMail node to fetch unread messages, process them through a LangChain toolkit, and send replies—all without human intervention. The MCP integration lets Claude Code or similar agents invoke buildJmapRequestTool and buildHelpTool from ts/src/langchain/mod.ts to construct and execute JMAP requests fluently, leveraging the model's existing familiarity with the protocol.

Code Health & Issues

The static analysis identified 27 findings across 6 high and 21 medium severity:

  • [HIGH/soundness] Import cycle member x3: files ts/src/lib/agent/jmap/agent-jmap.ts, agent-jmap-email-charset.ts, agent-jmap-blob-upload.ts participate in circular dependencies.
  • [HIGH/cognitive_load] Deep nesting x7: integrations/skill/atomicmail/lib/esm/lib/agent/jmap/agent-jmap.js, py/src/atomicmail/mcp_server.py, integrations/skill/atomicmail/lib/esm/_dnt.polyfills.js have max indentation depth 7.
  • [HIGH] Pin third-party GitHub Actions to a commit SHA: .github/workflows uses @vN tags for denoland/setup-deno@v2, openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0—tags can move, so actions running with secrets are unpredictable.
  • [HIGH] Make CI invoke the test suite: 43 test files exist but none of the 4 GitHub Actions workflows read include a test execution step.
  • [HIGH] Open a pull request instead of pushing to the default branch: publish-skills.yml uses git push that lands directly on the deploying branch with no test having run against the result.
  • [MEDIUM] Broad exception handling x4: py/src/atomicmail/session.py, py/src/atomicmail/jwt_utils.py, integrations/dify/atomicmail/utils/dify_kv_store.py have bare except clauses that swallow errors indiscriminately.
  • [MEDIUM] High branching density x9: ts/src/lib/agent/jmap/agent-jmap-blob-limits.ts has 59 branch points over 194 lines; same file in the skill integration and ts/src/lib/agent/session/agent-resolve-config.js.
  • [MEDIUM] Hub module: ts/src/lib/agent/session/agent-credentials-store.ts and ts/src/mcp/version.ts are depended on by 13 modules each—churn here has high-blast-radius impact.
  • [MEDIUM/clarity] Duplicated code blocks: 1346 repeated 6-line blocks across 122 files in the Dify integration, particularly in test and tool files.
  • [MEDIUM] Oversized file: py/src/atomicmail/jmap_request.py at 793 code lines.
  • [LOW] Missing convention files: .editorconfig, .gitattributes, and formatter config are absent.
  • [LOW] No timeout-minutes on 3 workflow jobs, risking overlap behind the two-hourly schedule.
  • [MEDIUM] No Dependabot/Renovate configured across 6 manifests.
  • [MEDIUM] No dependency vulnerability scan gate in CI.
  • [MEDIUM] assets/atomic-mail-agentic-demo.gif at 8.0MB should be tracked with Git LFS or moved to object storage.

The Bottom Line

This is a well-structured portfolio of 4 practical projects that successfully solve the agent email problem with JMAP and proof-of-work onboarding. The TypeScript skill framework is solid and LangChain-integrated, and the Dify/n8n adapters extend reach across popular agent platforms. However, the Action pinning, missing test invocations, circular imports, and unguarded exception handling are concrete risks that should be addressed before any production deployment. Teams looking to give agents email autonomy will find the most value here, particularly those already working within the MCP or LangChain ecosystems.