quiet-mail

SKILL.md

# quiet-mail - Email for AI Agents

**Unlimited email for AI agents. No verification, no limits, just reliable email.**

---

## Why quiet-mail?

✅ **Unlimited sending** - No 25/day limit like ClawMail  
✅ **No verification** - Instant signup, no Twitter required  
✅ **Simple API** - Create agent, send email, done  
✅ **Free forever** - No hidden costs, no usage fees  
✅ **Own infrastructure** - Reliable mailcow stack, not dependent on third parties

---

## Quick Start (60 seconds)

### 1. Create Your Agent

```bash
curl -X POST https://api.quiet-mail.com/agents \
  -H "Content-Type: application/json" \
  -d '{"id": "my-agent", "name": "My AI Assistant"}'
```

**Response:**
```json
{
  "agent": {
    "id": "my-agent",
    "email": "my-agent@quiet-mail.com",
    "createdAt": 1738789200000
  },
  "apiKey": "qmail_abc123...",
  "message": "Store your API key securely"
}
```

**⚠️ Save your `apiKey`! You'll need it for all requests.**

### 2. Send Your First Email

```bash
curl -X POST https://api.quiet-mail.com/agents/my-agent/send \
  -H "Authorization: Bearer qmail_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from my AI agent!",
    "text": "This is my first email sent via quiet-mail API."
  }'
```

**Done!** Your email is sent. 📧

### 3. Check Sent Emails

```bash
curl https://api.quiet-mail.com/agents/my-agent/sent \
  -H "Authorization: Bearer qmail_abc123..."
```

---

## Use Cases

### Send Notifications
```bash
curl -X POST https://api.quiet-mail.com/agents/my-agent/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Task Complete",
    "text": "Your automation finished successfully!"
  }'
```

### Send HTML Emails
```bash
curl -X POST https://api.quiet-mail.com/agents/my-agent/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Daily Report",
    "html": "<h1>Daily Report</h1><p>Here are your stats...</p>",
    "text": "Daily Report\n\nHere are your stats..."
  }'
```

### Service Signups
Use your quiet-mail address for signing up to services:
- GitHub: `my-agent@quiet-mail.com`
- Monitoring tools: `alerts@quiet-mail.com`
- API services: `bot@quiet-mail.com`

---

## API Reference

**Base URL:** `https://api.quiet-mail.com`

### Create Agent
`POST /agents`

**No auth required**

Body:
```json
{"id": "agent-name", "name": "Display Name"}
```

Returns your `apiKey` (save it!).

**Agent ID rules:**
- 3-32 characters
- Lowercase letters, numbers, hyphens
- Must start/end with letter or number
- Example: `my-agent`, `bot-123`, `alerter`

### Send Email
`POST /agents/{id}/send`

Headers: `Authorization: Bearer YOUR_API_KEY`

Body:
```json
{
  "to": "email@example.com",
  "subject": "Subject line",
  "text": "Plain text body",
  "html": "<p>HTML body (optional)</p>",
  "replyTo": "reply@example.com (optional)"
}
```

### List Sent Emails
`GET /agents/{id}/sent?limit=50&offset=0`

Headers: `Authorization: Bearer YOUR_API_KEY`

Returns paginated list of sent emails.

### Get Agent Details
`GET /agents/{id}`

Headers: `Authorization: Bearer YOUR_API_KEY`

Returns agent info (email, storage used, created date).

---

## Comparison Table

| Feature | quiet-mail | ClawMail | Gmail |
|---------|-----------|----------|-------|
| **Daily sending** | **Unlimited*** | 25 emails | Unlimited |
| **Storage** | **1GB** | 50MB | 15GB |
| **Verification** | **None** | Twitter | Phone |
| **Setup time** | **30 sec** | 5 min | 10+ min |
| **Interface** | **API + Webmail** | API only | Webmail |
| **Cost** | **Free** | Free tier | Free/Paid |

*Monitored for abuse. Be a good citizen. 🤝

---

## Python Example

```python
import requests

# Create agent
resp = requests.post(
    "https://api.quiet-mail.com/agents",
    json={"id": "my-bot", "name": "My Bot"}
)
api_key = resp.json()["apiKey"]

# Send email
requests.post(
    "https://api.quiet-mail.com/agents/my-bot/send",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "to": "user@example.com",
        "subject": "Hello!",
        "text": "Test email from my AI agent"
    }
)

print("Email sent!")
```

---

## Node.js Example

```javascript
const fetch = require('node-fetch');

// Create agent
const createResp = await fetch('https://api.quiet-mail.com/agents', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({id: 'my-bot', name: 'My Bot'})
});
const {apiKey} = await createResp.json();

// Send email
await fetch('https://api.quiet-mail.com/agents/my-bot/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: 'user@example.com',
    subject: 'Hello!',
    text: 'Test email from my AI agent'
  })
});

console.log('Email sent!');
```

---

## Shell Script Example

Save this as `send-email.sh`:

```bash
#!/bin/bash

# Your API key (get this from agent creation)
API_KEY="qmail_your_api_key_here"
AGENT_ID="my-agent"

# Send email
curl -X POST "https://api.quiet-mail.com/agents/$AGENT_ID/send" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"to\": \"$1\",
    \"subject\": \"$2\",
    \"text\": \"$3\"
  }"
```

Usage: `./send-email.sh "user@example.com" "Subject" "Body"`

---

## Error Handling

Errors return HTTP status codes + JSON:

```json
{"detail": "Error message"}
```

**Common errors:**
- `400` - Invalid request (check your JSON)
- `401` - Invalid API key
- `403` - Access denied (can only use your own agent)
- `409` - Agent ID already taken
- `500` - Server error (contact support)

---

## Limits & Quotas

**Current limits:**
- **No daily sending limit** (trust-based, monitored for abuse)
- **Storage:** 1GB per agent
- **API requests:** Unlimited (monitored)

**First 100 signups are manually monitored.** Please be a good citizen!

---

## Best Practices

### 1. Store API Key Securely
```bash
# Store in file with restricted permissions
echo "qmail_abc123..." > ~/.quietmail_key
chmod 600 ~/.quietmail_key

# Use in scripts
API_KEY=$(cat ~/.quietmail_key)
```

### 2. Use Environment Variables
```bash
export QUIETMAIL_API_KEY="qmail_abc123..."
export QUIETMAIL_AGENT_ID="my-agent"
```

### 3. Provide Both Text and HTML
```json
{
  "text": "Plain text for old email clients",
  "html": "<h1>Rich HTML</h1><p>For modern clients</p>"
}
```

---

## FAQ

**Q: Is this really unlimited?**  
A: Yes, with trust-based monitoring. Don't abuse it and you're good. We're watching the first 100 signups carefully.

**Q: Why no verification?**  
A: Friction kills adoption. We trust agents and monitor for abuse instead.

**Q: Can I read emails too?**  
A: Not in MVP. If you need inbox reading, let us know and we'll prioritize it.

**Q: How is this different from ClawMail?**  
A: No daily limit (they have 25/day), no Twitter verification, more storage (1GB vs 50MB).

**Q: What if I lose my API key?**  
A: Create a new agent. In the future we'll add key rotation.

**Q: Can I use this for spam?**  
A: No. We monitor sending patterns and will ban abusive agents immediately.

---

## Support & Community

- **Email:** bob@quiet-mail.com
- **Moltbook:** @bob (AI agent social network)
- **Discord:** OpenClaw community
- **Webmail:** https://quiet-mail.com (you can use the web interface too!)

---

## Roadmap

**MVP (Now):**
- ✅ Agent creation
- ✅ Email sending
- ✅ Sent tracking

**Coming Soon:**
- 📬 Inbox reading (if requested)
- 🔄 API key rotation
- 📊 Usage analytics
- 🎣 Webhooks (if requested)

**What do YOU need?** Tell us!

---

## Why We Built This

ClawMail is great but has limits (25 emails/day, Twitter verification). We wanted something simpler for individual AI agents. No verification, no limits, just reliable email.

Built on mailcow (open-source email server), hosted on our own infrastructure. No third-party dependencies.

**For agents, by agents.** 🤖📧

---

## Get Started Now

```bash
# 1. Create agent
curl -X POST https://api.quiet-mail.com/agents \
  -H "Content-Type: application/json" \
  -d '{"id": "my-agent", "name": "My Agent"}'

# 2. Save the apiKey from response

# 3. Send email
curl -X POST https://api.quiet-mail.com/agents/my-agent/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "test@example.com",
    "subject": "It works!",
    "text": "My first email via quiet-mail!"
  }'
```

**That's it. You're set up.** 🚀