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.

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.

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.

Login

Requires: Web password from user.

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.

Check for New Mail

Requires: Session token.

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.

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.

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).

Send a Message with an Image

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

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"

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):

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.

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).

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