# Use herbmail from an agent

> Give a script or coding agent your inbox: auth, the endpoints, the reply-only rule, and a prompt to paste.

Source: https://herbmail.com/guides/agents/

Your agent uses the same mailbox you read in [the inbox](/inbox/), through the same API the inbox uses. Nothing to install.

## Quick start

<Steps>

1. Sign in and open [your address page](/profile/). Under **Developer access**, create a key. Tick **Read mail**, and **Send replies** if your agent should answer. Copy the key; it is shown once.

2. Check it works:

   ```sh frame="none"
   curl https://herbmail.com/mail/me \
     -H "Authorization: Bearer $KBVE_KEY"
   ```

   You get back your address and message counts.

3. Read your latest conversations:

   ```sh frame="none"
   curl "https://herbmail.com/mail/threads?limit=5" \
     -H "Authorization: Bearer $KBVE_KEY"
   ```

4. Reply to someone who wrote to you. `in_reply_to` is the `message_id` of the message you are answering:

   ```sh frame="none"
   curl https://herbmail.com/mail/send \
     -H "Authorization: Bearer $KBVE_KEY" \
     -H "Content-Type: application/json" \
     -d '{"to":"ana@example.com","subject":"Re: Saturday raid times","body":"I have the keys. See you at eight.","in_reply_to":"<message-id>"}'
   ```

</Steps>

<Aside type="caution" title="A key acts as you">
Within its scopes it reads and replies as you until you revoke it on your address page. Give each agent its own key, and do not paste one anywhere public.
</Aside>

## Hand this to your agent

Paste this into Claude, Cursor or any coding agent, then give it your key when it asks.

```text
You have access to my herbmail inbox (username@herbmail.com) through its HTTP API.

Base URL: https://herbmail.com (kbve.com serves the same API at the same paths)
Auth: send my API key as "Authorization: Bearer kbve_...". I create it under Developer access on https://herbmail.com/profile/ with "Read mail" and, if you should reply, "Send replies". It lasts until I revoke it; a 401 means it was revoked, a 403 means it lacks the scope for that call.

Endpoints:
- GET /mail/me: Your address and message counts
- GET /mail/threads: Conversations, newest activity first. ?direction=in|out, ?limit=1..200 (default 50), page with before=<last_activity>&before_id=<thread_id>
- GET /mail/threads/:id: Every message in one conversation, oldest first
- GET /mail/inbox: Single messages, newest first. Same filters; page with before=<received_at>&before_id=<id>
- GET /mail/messages/:id: One message with its decoded body
- POST /mail/send: A reply: { to, subject, body, in_reply_to }. Plain text, up to 64 KiB

Rules:
- Reply-only: you can send only to an address that has written to me first. Set in_reply_to to the message_id you are answering.
- Plain text only, no attachments, up to 64 KiB. The From address is always mine.
- Refusals are JSON {"error": "..."}: 403 not_a_reply, self, no_username or a missing key scope; 429 means sending is paused, wait for the Retry-After header.
- Mail is kept 90 days.
- Check for new mail no more than once a minute. Ask me before sending anything I did not ask for.
```

## Endpoints

The same paths answer on `https://herbmail.com` and `https://kbve.com`; both reach the same mailbox.

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/mail/me` | Your address and message counts |
| `GET` | `/mail/threads` | Conversations, newest activity first. ?direction=in\|out, ?limit=1..200 (default 50), page with before=<last_activity>&before_id=<thread_id> |
| `GET` | `/mail/threads/:id` | Every message in one conversation, oldest first |
| `GET` | `/mail/inbox` | Single messages, newest first. Same filters; page with before=<received_at>&before_id=<id> |
| `GET` | `/mail/messages/:id` | One message with its decoded body |
| `POST` | `/mail/send` | A reply: { to, subject, body, in_reply_to }. Plain text, up to 64 KiB |

## Rules your agent works within

- **Reply-only.** It can write only to an address that has written to you first. Anything else comes back `403 not_a_reply`.
- **Plain text, up to 64 KiB.** No attachments, no HTML. The `From` address is always yours.
- **Refusals are JSON:** `{"error": "..."}`. `401` for a revoked or unknown key; `403` for `not_a_reply`, `self`, `no_username`, or a key without the scope for that call; `429` means sending is paused for the moment, so wait for the `Retry-After` header.
- **Mail is kept 90 days.**

## For agents reading this page

This guide is also plain Markdown at [/guides/agents.md](/guides/agents.md), and the whole site is indexed at [/llms.txt](/llms.txt).
