@agentuity/agentmail

Project email setup and management for any Node project. Requires Node.js 24+. Eve projects also get the optional @agentuity/eve-agentmail channel integration. Management requires a verified @agentuity.com Google account.

Prompt for your coding agent

Set up email for this project using npx --yes @agentuity/agentmail init --json.
Derive the address from package.json unless I specify one. Reuse existing setup.
If needs_auth is returned, show me its verification URL and code and rerun after
I approve. Read the installed .agents/skills/agentmail/SKILL.md. Keep runtime
secrets in .env and never print them. Connect the actual deployed HTTPS webhook
URL when receiving is needed; ask me if it is not available in project config.
Use the default real-email verification, resume with verify --json, and report
incomplete stages accurately. Preserve edited files and existing .env values.

Get started

Run from your project's directory:

npx @agentuity/agentmail login # approve this device once via Google
npx @agentuity/agentmail init # infer address from package.json
npx @agentuity/agentmail init --email support
# Several organization mailboxes in a non-Eve app; one project sending key:
npx @agentuity/agentmail init --mailbox lawns=app-lawns --mailbox windows=app-windows
npx @agentuity/agentmail init --url https://my-agent.example/webhooks/agentmail
npx @agentuity/agentmail doctor --json
npx @agentuity/agentmail verify --json

Non-Eve projects can add named mailboxes with repeated --mailbox name=email; later setup reuses them without adding Eve dependencies or mounts. The original package-name mailbox is retained. All mailboxes share the existing project sending key.

Multi-agent Eve projects get one address per root agent and one sending key for the project. Override with repeated --agent name=email and --agent-url name=url. The generated mounts fix each agent's sender and verify signed webhooks. .agents/skills/agentmail/SKILL.md teaches coding agents the CLI flow.

init installs that skill automatically in every project. Projects without Eve receive a mailbox, runtime sending key, and webhook secret without installing Eve. A custom webhook receiver must verify Agent Mail signatures and support the signed webhook.test probe.

Device and project management credentials use macOS Keychain; other platforms use a private file under ~/.config/agentmail. --credential-dir explicitly selects a private file store for CI/testing. Runtime sending keys and per-agent webhook secrets go in .env (mode 0600, added to .gitignore). .agentmail.json is safe to commit. Device approval expires after ten minutes; inactive device credentials expire after thirty days and project credentials after seven days. Rerun init to renew authorization.

For local tarball testing, pack this package with npm pack -w @agentuity/agentmail. Run npx --yes --package /ABS/PATH/agentuity-agentmail-0.2.0.tgz agentmail init. Eve projects also require the local extension: pack @agentuity/eve-agentmail and pass --extension-package /ABS/PATH/agentuity-eve-agentmail-0.2.0.tgz on the first init.

--json never prints secrets. needs_auth/needs_input exit 2; errors exit 1. Setup can be rerun after authorization or deployment. Existing edited generated files and unrelated .env values are preserved. Receiving is reported ready only after the selected connection or email verification succeeds. No email-fetch API is exposed. Use --help for management and rotation commands.

Agent mode (init --json and webhook set --json) automatically verifies a real email round trip. It sends a tagged test email from each mailbox to itself and reports sending, receipt, R2 storage, webhook acceptance, and Eve acceptance when applicable. It waits up to 60 seconds; --verification-timeout 0..300 changes the wait. Without a receiver URL, mailbox verification can succeed while webhook delivery remains pending. A receiver accepting an email does not prove the model completed its turn.

verify --json resumes the saved test. Repeated setup with the same key and receiver reuses the same idempotency key and sends no duplicate email. --new-test explicitly starts a fresh test; an unknown provider outcome must be resolved before a new test can start. Changed keys or webhook configuration trigger a new verification. Human mode can opt in with init --verify; init --json --skip-verify explicitly skips email verification and uses a signed connection probe instead.

Eve discovery supports instructions-only agents, standard agent/ directories, and workspace members with nested or flat agent files. When adding the email extension to a new Eve project, init declares Eve 0.72.1 as a dependency if the project does not already declare Eve; existing Eve versions are preserved.