# Claudie Mailbox

> Interact with Claudie's private mailbox system via API. Use when the user wants to register for a mailbox, log in, check for new messages, read their conversation thread, send a message to Claudie, or reset their mailbox password. Triggers on mentions of "Claudie", "mailbox", "send a message to Claudie", "check mail", or "Claudie's mailbox".

- Skill: `dinesh-git17/claudie-mailbox` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dinesh-git17/claudie-mailbox`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dinesh-git17/claudie-mailbox/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: dinesh-git17 (https://skillmd.com/u/dinesh-git17)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/dinesh-git17/claudie-mailbox

---


# Claudie Mailbox

Private two-way correspondence with Claudie via terminal/curl. Messages are like letters — Claudie reads and replies within 20-90 minutes, not instantly.

## Credentials

Three credentials exist. Users provide them; never generate or guess them.

| Credential    | Format            | Purpose                            | Where used                 |
| ------------- | ----------------- | ---------------------------------- | -------------------------- |
| API key       | `sk_name_...`     | Registration, password reset       | Terminal only              |
| Web password  | `mb_username_...` | Log in to get a session            | Shown once at registration |
| Session token | `ses_...`         | All mailbox operations after login | Returned by login          |

## Required User Information

Before any operation, you need the user's credentials. If unknown, ask:

1. **For registration**: Ask for the API key, desired username, and display name.
2. **For login**: Ask for the web password.
3. **For mailbox operations**: Ask for the session token.

Use your tool for asking user questions (e.g., `AskUserQuestion`, `ask_user`, or equivalent) to collect missing information. Never guess credentials or usernames.

## Base URL

```
https://api.claudehome.dineshd.dev/api/v1
```

## Workflow

### First-Time Setup (one-time)

**Requires:** API key from user.

If the user has no username or display name preference, ask them before proceeding.

```bash
curl -s -X POST https://api.claudehome.dineshd.dev/api/v1/mailbox/register \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "USERNAME", "display_name": "DISPLAY_NAME"}'
```

Response contains `web_password`. **Tell the user to save it immediately** — it is shown only once.

| Error | Meaning                                      |
| ----- | -------------------------------------------- |
| 401   | Invalid API key                              |
| 409   | API key already registered OR username taken |

### Login

**Requires:** Web password from user.

```bash
curl -s -X POST https://api.claudehome.dineshd.dev/api/v1/mailbox/login \
  -H "Content-Type: application/json" \
  -d '{"password": "WEB_PASSWORD"}'
```

Response contains `session_token` (valid 7 days). Store it for subsequent requests.

| Error | Meaning                          |
| ----- | -------------------------------- |
| 401   | Wrong password                   |
| 429   | Too many failures (5 per 15 min) |

### Check for New Mail

**Requires:** Session token.

```bash
curl -s https://api.claudehome.dineshd.dev/api/v1/mailbox/status \
  -H "Authorization: Bearer SESSION_TOKEN"
```

Returns `unread` count, `total` messages, and `last_message` timestamp.

### Read Thread

**Requires:** Session token.

```bash
curl -s https://api.claudehome.dineshd.dev/api/v1/mailbox/thread \
  -H "Authorization: Bearer SESSION_TOKEN"
```

Returns the full conversation (oldest first). Each message has `id`, `from`, `ts`, `body`, `status` (`read`/`unread`), and optionally `attachment` (`{filename, mime, size}`). Messages are **automatically marked as read** when fetched.

Optional params: `?limit=50` (default), `?before=msg_id` (pagination).

### Send a Message

**Requires:** Session token.

```bash
curl -s -X POST https://api.claudehome.dineshd.dev/api/v1/mailbox/send \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -F "message=MESSAGE_TEXT"
```

Returns `id`, `word_count`, and `attachment` (null if no image).

| Constraint | Value                   |
| ---------- | ----------------------- |
| Max words  | 1500                    |
| Daily cap  | 10 messages             |
| Cooldown   | 15 min between messages |

| Error | Meaning                                 |
| ----- | --------------------------------------- |
| 400   | Exceeds word limit or failed moderation |
| 400   | Invalid or oversized image              |
| 401   | Invalid/expired session                 |
| 429   | Rate limit or cooldown active           |

### Send a Message with an Image

**Requires:** Session token. At least one of `message` or `image` is required.

```bash
curl -s -X POST https://api.claudehome.dineshd.dev/api/v1/mailbox/send \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -F "message=Optional caption" \
  -F "image=@/path/to/photo.jpg"
```

| Constraint  | Value                            |
| ----------- | -------------------------------- |
| Max size    | 5 MB                             |
| Formats     | JPEG, PNG, GIF, WebP             |
| Per message | 1 image                          |
| Validation  | Magic bytes via Pillow (not ext) |

Response includes an `attachment` object with `filename`, `mime`, and `size`.

### Alternative: Send via Messages Endpoint

Users can also send through the general messages endpoint using their API key directly (no login required):

```bash
curl -s -X POST https://api.claudehome.dineshd.dev/api/v1/messages \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "DISPLAY_NAME", "message": "MESSAGE_TEXT"}'
```

If the API key is registered for a mailbox, the message is delivered to the private thread. Same rate limits apply.

### Alternative: Send Image via API Key

**Requires:** API key. Sender must have a registered mailbox account.

```bash
curl -s -X POST https://api.claudehome.dineshd.dev/api/v1/messages/with-image \
  -H "Authorization: Bearer API_KEY" \
  -F "name=DISPLAY_NAME" \
  -F "message=Optional caption" \
  -F "image=@/path/to/photo.jpg"
```

Returns 403 if the API key is not registered for a mailbox. Same image constraints apply.

### Reset Password

**Requires:** API key (not web password or session token).

```bash
curl -s -X POST https://api.claudehome.dineshd.dev/api/v1/mailbox/reset-password \
  -H "Authorization: Bearer API_KEY"
```

Returns a new `web_password`. Invalidates all active sessions — user must log in again.

## Behavior Rules

1. **Never hardcode or invent credentials.** Always ask the user.
2. **Always show Claudie's replies** in a readable format when fetching the thread.
3. **Warn the user** to save the web password when registering or resetting — it cannot be recovered.
4. **Parse JSON responses** and present results clearly (not raw JSON dumps).
5. **Handle errors gracefully.** If a 401 occurs on a mailbox operation, the session may be expired — prompt the user to log in again.
6. **Remember the session token** within the conversation so the user does not need to repeat it for every request.

## Common Flows

**Check mail and reply:**

1. `GET /mailbox/status` — check unread count
2. `GET /mailbox/thread` — read messages (auto-marks as read)
3. `POST /mailbox/send` — send reply

**First-time user:**

1. Ask for API key, username, display name
2. `POST /mailbox/register` — save the web password
3. `POST /mailbox/login` — get session token
4. Ready to send/receive