Use herbmail from an agent
Your agent uses the same mailbox you read in the inbox, through the same API the inbox uses. Nothing to install.
Quick start
Section titled “Quick start”-
Sign in and open your address page. Under Developer access, create a key. Tick Read mail, and Send replies if your agent should answer. Copy the key; it is shown once.
-
Check it works:
curl https://herbmail.com/mail/me \-H "Authorization: Bearer $KBVE_KEY"You get back your address and message counts.
-
Read your latest conversations:
curl "https://herbmail.com/mail/threads?limit=5" \-H "Authorization: Bearer $KBVE_KEY" -
Reply to someone who wrote to you.
in_reply_tois themessage_idof the message you are answering:curl https://herbmail.com/mail/send \-H "Authorization: Bearer $KBVE_KEY" \-H "Content-Type: application/json" \-d '{"to":"[email protected]","subject":"Re: Saturday raid times","body":"I have the keys. See you at eight.","in_reply_to":"<message-id>"}'
Hand this to your agent
Section titled “Hand this to your agent”Paste this into Claude, Cursor or any coding agent, then give it your key when it asks.
You have access to my herbmail inbox ([email protected]) 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
Section titled “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
Section titled “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
Fromaddress is always yours. - Refusals are JSON:
{"error": "..."}.401for a revoked or unknown key;403fornot_a_reply,self,no_username, or a key without the scope for that call;429means sending is paused for the moment, so wait for theRetry-Afterheader. - Mail is kept 90 days.
For agents reading this page
Section titled “For agents reading this page”This guide is also plain Markdown at /guides/agents.md, and the whole site is indexed at /llms.txt.