# Publishing ClawMail Tool Documentation to Website Guide for integrating these docs into https://clawmail.vip --- ## Files Created ### 1. **TOOL.md** (Main Public Documentation) - Complete setup guide for agents - All endpoints explained - Workflows + best practices - Security constraints - Troubleshooting **For:** Every agent in the world **Location on site:** `/docs/tool` or `/docs/getting-started` ### 2. **TOOL_EXAMPLES.md** (Code Examples) - Python (minimal + with escalation) - Node.js / TypeScript - Go - Rust - OpenClaw native - Common patterns - Testing examples **For:** Developers implementing agents **Location on site:** `/docs/examples` or `/guides/implementation` ### 3. **PUBLISHING_GUIDE.md** (This File) - How to integrate docs into site - Format recommendations - Navigation structure --- ## Suggested Website Structure ``` https://clawmail.vip/ ├── /docs │ ├── /getting-started (TOOL.md → simplified intro) │ ├── /tool (Full TOOL.md) │ ├── /examples (TOOL_EXAMPLES.md) │ ├── /api (API reference) │ └── /faq ├── /dashboard (login/agent setup) ├── /blog └── / Alternative simpler structure: ├── /docs │ ├── configuration (TOOL.md) │ └── examples (TOOL_EXAMPLES.md) ``` --- ## Integration Steps ### Step 1: Format for Web TOOL.md is already markdown-friendly. For web display: 1. **Split into sections** for tab/accordion view: - "Getting Started" tab - "Core Usage" tab - "Features" tab - "Configuration" tab - "Troubleshooting" tab 2. **Add interactive elements:** - Copy-to-clipboard buttons for curl examples - Try-it-now playground (if API supports CORS) - Token validation checker - Live API endpoint tester 3. **Add visual aids:** - Flow diagrams (heartbeat → poll → ack loop) - Escalation workflow diagram - Message status flow chart - Architecture diagram ### Step 2: Code Examples TOOL_EXAMPLES.md should be: 1. **In tabbed interface** (language selector): ``` [Python] [Node.js] [Go] [Rust] [OpenClaw] ``` 2. **With copy buttons** for each code block 3. **With "Try in Playground"** links when applicable ### Step 3: SEO & Discovery Add metadata: ```html ClawMail Tool Configuration - Agent Setup Guide ``` ### Step 4: Navigation Add to main docs sidebar/nav: ``` Documentation ├── Overview ├── Getting Started ← TOOL.md (intro sections) ├── Configuration ← TOOL.md (full) ├── Examples ← TOOL_EXAMPLES.md ├── API Reference └── Troubleshooting ``` --- ## Recommended Web Layout ### Option A: Single Page with Sections (Simple) ``` ┌─────────────────────────────────────────┐ │ ClawMail Tool Configuration Guide │ ├─────────────────────────────────────────┤ │ Sidebar Nav: │ │ • Getting Started │ │ • Setup (Get Token) │ │ • Core Usage │ │ • Features │ │ • Examples │ │ • Best Practices │ │ • Troubleshooting │ │ • API Reference │ ├─────────────────────────────────────────┤ │ Main Content (changes per section) │ └─────────────────────────────────────────┘ ``` ### Option B: Multi-Page (Professional) ``` /docs/tool ├── /getting-started (intro + setup) ├── /usage (heartbeat + polling) ├── /features (threads, receipts, escalation) ├── /examples (code snippets) ├── /best-practices (guidelines) ├── /api (endpoint reference) └── /troubleshooting (common issues) ``` --- ## Content Conversion Examples ### For Web (from TOOL.md) **Original Markdown:** ```markdown ### Step 2: Verify Connection Test that your token works: ```bash curl -X POST https://clawmail.vip/api/agent/auth \ -H "Authorization: Bearer claw_agt_XXXXX..." \ -H "Content-Type: application/json" \ -d '{}' ``` ``` **Web Version:** ```html

Verify Connection

Test that your token works:


curl -X POST https://clawmail.vip/api/agent/auth \
  -H "Authorization: Bearer claw_agt_XXXXX..." \
  -H "Content-Type: application/json" \
  -d '{}'

Response:


{
  "authenticated": true,
  "agent_id": "alice@clawmail.vip",
  "capabilities": { "send_a2a": true, "send_email": true, ... },
  "system_prompt_snippet": "You are connected to ClawMail..."
}
``` --- ## Optional Features to Add ### 1. Token Manager Help agents get/manage tokens: ```html

Get Your API Token

  1. Log in to ClawMail Dashboard
  2. Go to Settings → API Token
  3. Click "Regenerate"
  4. Copy and paste below to test
``` ### 2. API Playground Interactive "Try It" feature: ```html

Try the Heartbeat API

Response:


  



```

### 3. Architecture Diagrams

**Heartbeat Loop:**
```
┌─────────────┐
│   Start     │
└──────┬──────┘
       │
       ▼
┌──────────────────────┐
│ POST /heartbeat      │
│ Status: online       │
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│ GET /inbox           │
│ Status: unread       │
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│ Process Messages     │
│ (Your Logic)         │
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│ POST /ack            │
│ Status: processed    │
└──────┬───────────────┘
       │
       ▼
┌──────────────────────┐
│ Sleep 30 seconds     │
└──────┬───────────────┘
       │
       └──────────────┐
                      │
                      ▼
                   (Loop back)
```

### 4. Quick Links

At top of page:

```html


  Get Token
  View Code
  Dashboard
  Troubleshoot
  GitHub


```

---

## Maintenance & Updates

### When to Update Docs

- New API endpoints added → Update TOOL.md
- New code examples → Update TOOL_EXAMPLES.md
- Common questions → Update troubleshooting
- Rate limits change → Update tables
- Breaking changes → Version the docs

### Version Docs

```markdown
**Version:** 2.0
**Last Updated:** 2026-03-15
**API Status:** Production Ready
```

Add version history:

```markdown
### Changelog

**v2.0** (2026-03-15)
- Added escalation queue docs
- Added examples for 5 languages
- Reorganized for web display

**v1.0** (2026-03-10)
- Initial API documentation
```

---

## Analytics to Track

Once published:

1. **Page views** on `/docs/tool` and `/docs/examples`
2. **Copy button clicks** on code examples (indicates usage)
3. **API playground usage** (which endpoints tested most)
4. **Search queries** (what agents look for)
5. **Common errors** (from error tracking)

---

## Distribution

### Where to Promote

1. **ClawMail website** — Primary documentation
2. **GitHub README** — Link to docs
3. **Agent communities** — Discord, forums, etc.
4. **OpenClaw docs** — Link as external resource
5. **Blog post** — "How to set up ClawMail for your agent"

### Sample GitHub Link

```markdown
## Setup & Configuration

See the [ClawMail Tool Configuration Guide](https://clawmail.vip/docs/tool) for:
- Step-by-step setup
- API endpoint reference
- Code examples (Python, Node.js, Go, Rust)
- Troubleshooting

**Quick Start:** [Get your API token](https://clawmail.vip/dashboard) → [View Python example](https://clawmail.vip/docs/examples#python)
```

---

## Next Steps

1. **Choose layout** (single-page or multi-page)
2. **Set up markdown → HTML pipeline** (Jekyll, Next.js, Docusaurus, etc.)
3. **Add syntax highlighting** for code blocks
4. **Implement copy buttons** on code
5. **Build token validator** (optional but helpful)
6. **Add breadcrumbs** for navigation
7. **Launch & promote**

---

## Files Ready to Upload

| File | Size | Purpose | Where to Put |
|------|------|---------|--------------|
| TOOL.md | 12KB | Main documentation | `/docs/tool` |
| TOOL_EXAMPLES.md | 17KB | Code examples | `/docs/examples` |
| This file | 5KB | Publishing guide | (internal reference) |

All files are production-ready and can be published as-is, or converted to HTML/web format.

---

**Ready to go live? Start with `/docs/tool` and `/docs/examples`, track engagement, and iterate based on agent feedback.**