mails - Moses Yebei

The Problem

AI agents need to send and receive email programmatically, but email infrastructure is fragmented: sending requires provider SDKs, receiving requires polling or webhooks, and extracting verification codes from HTML emails is bespoke work. mails wraps send, receive, search, and code extraction into one CLI and SDK with a pluggable provider chain.

What This Does

The repo is a TypeScript monorepo with two projects: src/ (CLI + SDK) and worker/ (Cloudflare Worker for receiving and sending). The CLI handles send, inbox, code, claim, and sync commands; the worker handles incoming email via Cloudflare Email Routing and exposes /api/send and /api/inbox endpoints.

Storage is provider-based: local SQLite (src/providers/storage/sqlite.ts), cloud PostgreSQL via db9.ai (src/providers/storage/db9.ts), or a remote Worker API (src/providers/storage/remote.ts). Sending uses a chain of Cloudflare Email Service then Resend, configurable via EMAIL_PROVIDERS.

How It Is Wired

Execution starts at main in src/cli/index.ts, which reaches 80 functions. The call graph shows loadConfig is called from 11 places — the widest blast radius — followed by fetch (9) and esc (8). src/core/types.ts is a hub with 28 modules importing it; changes there ripple broadly.

A typical inbox command traces: main -> inboxCommand -> getEmail, which hits the database via db.prepare('SELECT * FROM emails WHERE id = ?') — two hops to a DB effect. The worker's fetch handler in worker/src/index.ts routes to handleInbox, writing via env.DB.prepare(...). The worker also owns email, handleGetCode, and handleSync, and is the only file making outbound network calls.

The worker/src/index.ts file is the operational core: 19 functions, called from 7 files. Storage providers are split by responsibility — db9.ts owns column handling and SQL escaping, sqlite.ts owns local persistence, remote.ts owns the API client.

How To Use It

Setup: npm install -g mails or bun install -g mails.

Configuration: Copy .env.example to .env for local storage. For the worker, copy worker/.dev.vars.example to worker/.dev.vars and set EMAIL_PROVIDERS, API keys, and mailbox auth tokens. The CLI stores config in a user-level file managed by src/core/config.ts.

Running it: The CLI entry point is src/cli/index.ts, invoked as mails send --to user@example.com --subject "..." or mails inbox. The worker runs via wrangler dev in the worker/ directory, with worker/wrangler.toml defining routes and bindings.

Real-World Use

A support agent that watches a shared inbox: deploy the worker with Cloudflare Email Routing, run mails sync to pull new messages into local SQLite, extract verification codes with mails code, and auto-reply via mails send. The provider field in responses tells you whether Cloudflare or Resend delivered each message.

Code Health & Issues

Static analysis found 16 issues (3 high, 13 medium). High severity: hub modules in src/core/types.ts (28 dependents) and src/core/config.ts (19 dependents) — churn there is high-blast-radius; deep nesting in src/cli/commands/help.ts (indentation depth 10); and duplicated code blocks — 76 repeated 6-line blocks across 28 files.

Medium: high branching density in src/providers/storage/remote.ts, sqlite.ts, and core/storage.ts (59 branch points over 142 lines), plus an oversized test file test/unit/worker.test.ts at 735 lines.

Beyond the measured findings: no LICENSE file (default all-rights-reserved), wildcard CORS origin in worker/src/index.ts (Access-Control-Allow-Origin: '*'), unpinned GitHub Actions in .github/workflows/release.yml, continue-on-error on a correctness step, no Dependabot, and no dependency vulnerability scan in CI. The repo has a bun.lock but no npm lockfile.

The Bottom Line

The architecture is sound — clean provider abstraction, zero runtime dependencies, and a clear separation between CLI, worker, and storage. The main risks are operational: unpinned CI actions, wildcard CORS, and no license. Worth using for agent email workflows, but fix the security items before production deployment.

What the analyser found

Deployment readiness

4/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

91 files

TypeScript66
Markdown10
JSON4
TOML3
SQL2
YAML1

React

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["test<br/>34 modules"] g1["src<br/>24 modules"] g2["worker<br/>8 modules"] g0 -->|55| g1 g0 -->|8| g2 g2 -->|1| g1

Module dependencies

The 10 most depended-upon modules of 66, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_core_types["types"] n1_src_core_config["config"] n2_src_providers_send_resend["resend"] n3_src_providers_storage_remote["remote"] n4_src_providers_storage_sqlite["sqlite"] n5_src_core_storage["storage"] n6_src_core_api_url["api-url"] n7_worker_src_providers_types["types"] n8_src_core_send["send"] n9_src_providers_send_hosted["hosted"] n1_src_core_config --> n0_src_core_types n1_src_core_config --> n6_src_core_api_url n8_src_core_send --> n0_src_core_types n8_src_core_send --> n1_src_core_config n8_src_core_send --> n2_src_providers_send_resend n8_src_core_send --> n9_src_providers_send_hosted n5_src_core_storage --> n0_src_core_types n5_src_core_storage --> n1_src_core_config n5_src_core_storage --> n6_src_core_api_url n5_src_core_storage --> n4_src_providers_storage_sqlite n5_src_core_storage --> n3_src_providers_storage_remote n9_src_providers_send_hosted --> n0_src_core_types n9_src_providers_send_hosted --> n6_src_core_api_url n2_src_providers_send_resend --> n0_src_core_types n3_src_providers_storage_remote --> n0_src_core_types n4_src_providers_storage_sqlite --> n0_src_core_types

Findings

MediumNo LICENSE file - unclear usage/redistribution rights root
LowDependencies declared without a lockfile - non-reproducible builds package.json

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium2

low1

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

oven-sh/setup-bun@v2, softprops/action-gh-release@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Replace the wildcard CORS origin with an explicit allow listhigh

worker/src/index.ts

Access-Control-Allow-Origin': '*'

Any page on the internet can call the API with the browser's cookies attached, so a logged-in visitor to an unrelated site performs authenticated requests without knowing, and the wildcard combined with credentials is the exact configuration browsers refuse for that reason.

Fix: List the origins the API actually serves, and never pair a wildcard with credentials.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/release.yml

line 72 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set timeout-minutes on the workflow jobslow

.github/workflows/release.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.