mails

Mails — Email for AI Agents

Overview

mails gives agents a real @mails.dev mailbox: send, receive, and extract verification codes. The core agent loop is:

claim mailbox (once) → send email → wait for code → done

---

Step 1 — Install

npm install -g mails
mails version   # should print a version number

---

Step 2 — Claim a mailbox (one-time, requires human approval)

mails claim <pick-a-name>

With a browser (local machine): browser opens automatically; human approves; CLI saves credentials.

Without a browser (sandbox, SSH, CI — this is the common agent case):

Claiming [email protected]

To complete, ask a human to visit:

  https://mails.dev

and enter this code:

  KDNR-CHPC

Waiting...

Relay the URL and code to the human. Once confirmed, credentials are saved to ~/.mails/config.json.

Verify setup:

mails config get mailbox   # prints your address
mails config get api_key   # prints mk_...

---

Step 3 — The verification code pattern (primary agent use case)

This is the core loop. Long-polls for a code, pipes cleanly to stdout, exits 1 on timeout.

# Basic: wait up to 30s
CODE=$(mails code --to [email protected] --timeout 30)

# In a script — check success before using
if CODE=$(mails code --to [email protected] --timeout 60); then
  echo "Got code: $CODE"
else
  echo "Timed out — no code arrived"
fi

Trigger the email first (sign-up, login, etc.), then immediately start polling:

# 1. Trigger the email (sign up, request OTP, etc.) — example only
curl -X POST https://someservice.com/auth/send-code \
  -d "[email protected]"

# 2. Wait for it
CODE=$(mails code --to [email protected] --timeout 60)
echo "Verification code: $CODE"

---

Step 4 — Send email

# Basic send (100 free/month included)
mails send --to [email protected] --subject "Hello" --body "World"

# With attachment
mails send --to [email protected] --subject "Report" --body "See attached" --attach report.pdf