mails

Category: Data & AI | Uploader: chekusu | Downloads: 0 | Version: v1.0（Latest）

Send and receive emails. Get a free `@mails.dev` mailbox or use your own domain.

Changelog: Source: GitHub https://github.com/chekusu/mails

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 release.yml 1.8 KB
📁 src/
- 📁 cli/
  - 📁 commands/
    
    📄 claim.ts 3.1 KB
    
    📄 code.ts 1.3 KB
    
    📄 config.ts 1.0 KB
    
    📄 help.ts 1.7 KB
    
    📄 inbox.ts 2.0 KB
    
    📄 send.ts 1.1 KB
  - 📄 index.ts 1.1 KB
- 📁 core/
  - 📄 config.ts 1.2 KB
  - 📄 receive.ts 712 B
  - 📄 send.ts 1.2 KB
  - 📄 storage.ts 975 B
  - 📄 types.ts 1.6 KB
- 📁 providers/
  - 📁 send/
    
    📄 resend.ts 1.1 KB
  - 📁 storage/
    
    📄 db9.ts 5.4 KB
    
    📄 sqlite.ts 4.2 KB
- 📄 index.ts 569 B
📁 test/
- 📁 e2e/
  - 📄 claim-flow.test.ts 8.5 KB
  - 📄 claim-interactive.ts 2.2 KB
  - 📄 flow.test.ts 6.1 KB
  - 📄 live.test.ts 5.8 KB
- 📁 unit/
  - 📄 cli.test.ts 2.1 KB
  - 📄 config.test.ts 2.1 KB
  - 📄 db9.test.ts 9.4 KB
  - 📄 extract-code.test.ts 1.8 KB
  - 📄 resend.test.ts 2.8 KB
  - 📄 send.test.ts 3.2 KB
  - 📄 sqlite.test.ts 6.2 KB
  - 📄 storage.test.ts 3.3 KB
  - 📄 worker.test.ts 2.8 KB
📁 worker/
- 📁 src/
  - 📄 extract-code.ts 856 B
  - 📄 index.ts 5.6 KB
- 📄 bun.lock 21.3 KB
- 📄 package.json 414 B
- 📄 schema.sql 793 B
- 📄 tsconfig.json 262 B
- 📄 wrangler.toml 181 B
📄 .env.example 156 B
📄 .gitignore 52 B
📄 bun.lock 1.1 KB
📄 bunfig.toml 23 B
📄 package.json 1.4 KB
📄 plan.md 13.9 KB
📄 README.ja.md 4.1 KB
📄 README.md 5.2 KB
📄 README.zh.md 4.0 KB
📄 research.md 4.1 KB
📄 skill.md 6.3 KB
📄 tsconfig.json 492 B

SKILL.md

# mails — Email for AI Agents

Send and receive emails. Get a free `@mails.dev` mailbox or use your own domain.

## Onboarding (follow these steps in order)

### Step 1: Install

```bash
npm install -g mails
```

Verify: `mails version` should print a version number.

### Step 2: Claim a mailbox

You need a `@mails.dev` email address. This requires a human to approve (one-time).

```bash
mails claim <pick-a-name>
```

**If you have a browser** (local machine): it will open automatically. The human approves, and the CLI receives the API key.

**If you don't have a browser** (sandbox, SSH, CI): the CLI will show a code like this:

```
  Claiming myagent@mails.dev

  To complete, ask a human to visit:

    https://mails.dev/claim

  and enter this code:

    KDNR-CHPC

  Waiting...
```

Relay the URL and code to your human user. Once they confirm, the CLI will continue and save the credentials to `~/.mails/config.json`.

Verify: `mails config get mailbox` should print your address. `mails config get api_key` should print `mk_...`.

### Step 3: Test receiving — check your inbox

Your mailbox is ready to receive emails. Check it:

```bash
mails inbox
```

Expected: `No emails found.` (empty inbox is normal for a new mailbox).

### Step 4: Configure sending

To send emails, you need a Resend API key. Get one at https://resend.com, then:

```bash
mails config set resend_api_key re_YOUR_KEY
mails config set default_from "YourAgent <yourname@mails.dev>"
```

Note: sending from `@mails.dev` requires the domain to be verified on Resend. If you use a different sending domain (e.g. your own), set `default_from` accordingly.

### Step 5: Test sending

Send a test email to yourself:

```bash
mails send --to YOUR_MAILBOX@mails.dev --subject "Test" --body "Hello from mails"
```

Replace `YOUR_MAILBOX@mails.dev` with the address from Step 2. If sending from the same domain fails (Resend may suppress same-domain delivery), try sending to a different email address.

Verify: `Sent via resend (id: ...)` confirms the email was sent.

### Step 6: Test verification code extraction

Send an email containing a code to your mailbox (from a different domain), then query it:

```bash
mails code --to YOUR_MAILBOX@mails.dev --timeout 30
```

This long-polls for up to 30 seconds. When an email with a verification code arrives, it prints the code to stdout. If no code arrives, it exits with code 1.

### Onboarding complete

You now have:
- `~/.mails/config.json` with your mailbox, API key, and send config
- A working `@mails.dev` address that receives emails
- The ability to send emails via Resend

---

## CLI Reference

```
mails claim <name>        Claim name@mails.dev (max 10 per user)
mails send                Send an email
mails inbox               List received emails
mails code                Wait for a verification code
mails config              View or modify configuration
mails help                Show help
mails version             Show version
```

### claim

```bash
mails claim myagent
```

Opens browser (or shows device code) for human approval. On success, saves `mailbox` and `api_key` to config. Each human user can create up to 10 mailboxes.

### send

```bash
mails send --to user@example.com --subject "Subject" --body "Plain text body"
mails send --to user@example.com --subject "Subject" --html "<h1>HTML body</h1>"
mails send --from "Name <email>" --to user@example.com --subject "Subject" --body "Text"
```

Uses `default_from` from config if `--from` is not specified. Requires `resend_api_key` in config.

### inbox

```bash
mails inbox                           # List recent emails (uses mailbox from config)
mails inbox --mailbox addr@mails.dev  # Specify mailbox
mails inbox <email-id>                # Show full email details
```

### code

```bash
mails code --to addr@mails.dev              # Wait 30s (default)
mails code --to addr@mails.dev --timeout 60 # Wait 60s
```

Prints the verification code to stdout (for piping: `CODE=$(mails code --to ...)`). Details go to stderr. Exits with code 1 if no code received within timeout.

### config

```bash
mails config                    # Show all
mails config set <key> <value>  # Set a value
mails config get <key>          # Get a value
mails config path               # Show config file path
```

Config file: `~/.mails/config.json`

| Key | Set by | Description |
|-----|--------|-------------|
| `mailbox` | `mails claim` | Your @mails.dev receiving address |
| `api_key` | `mails claim` | API key for inbox/code queries (mk_...) |
| `resend_api_key` | manual | Resend API key for sending emails |
| `default_from` | manual | Default sender address |
| `storage_provider` | manual | `sqlite` (default) or `db9` |

## SDK (Programmatic Usage)

```typescript
import { send, getInbox, waitForCode } from 'mails'

// Send an email
const result = await send({
  to: 'user@example.com',
  subject: 'Hello',
  text: 'World',
})

// List inbox
const emails = await getInbox('myagent@mails.dev', { limit: 10 })

// Wait for verification code
const code = await waitForCode('myagent@mails.dev', { timeout: 30 })
if (code) console.log(code.code) // "123456"
```

## API (Direct HTTP)

For agents that prefer raw HTTP over the CLI/SDK.

### Claim flow (no auth)

```bash
# Start session
curl -X POST https://api.mails.dev/v1/claim/start \
  -H "Content-Type: application/json" \
  -d '{"name": "myagent"}'
# → {"session_id": "xxx", "device_code": "ABCD-1234", "expires_in": 600}

# Poll until human confirms (every 2s)
curl "https://api.mails.dev/v1/claim/poll?session=xxx"
# → {"status": "pending"}
# → {"status": "complete", "mailbox": "myagent@mails.dev", "api_key": "mk_xxx"}
```

### Authenticated endpoints (requires API key from claim)

```bash
# List inbox
curl -H "Authorization: Bearer mk_YOUR_API_KEY" \
  "https://api.mails.dev/v1/inbox"

# Wait for verification code
curl -H "Authorization: Bearer mk_YOUR_API_KEY" \
  "https://api.mails.dev/v1/code?timeout=30"

# Get email detail
curl -H "Authorization: Bearer mk_YOUR_API_KEY" \
  "https://api.mails.dev/v1/email?id=EMAIL_ID"
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MAILS_API_URL` | `https://api.mails.dev` | Override API base URL |
| `MAILS_CLAIM_URL` | `https://mails.dev/claim` | Override claim page URL |

## Links

- Website: https://mails.dev
- npm: https://www.npmjs.com/package/mails
- GitHub: https://github.com/chekusu/mails

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

mails

Directory Structure

SKILL.md

Report

Notice