Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license
This commit is contained in:
@@ -0,0 +1,95 @@
|
||||
---
|
||||
name: agentmail
|
||||
description: Use when an agent needs AgentMail CLI email inboxes.
|
||||
version: 1.0.0
|
||||
author: Haakam Aujla (Haakam21), AgentMail
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [Email, CLI, AgentMail, Communication]
|
||||
homepage: https://agentmail.to
|
||||
prerequisites:
|
||||
commands: [agentmail]
|
||||
required_environment_variables:
|
||||
- name: AGENTMAIL_API_KEY
|
||||
prompt: AgentMail API key (starts with am_)
|
||||
help: "Create one at https://console.agentmail.to — or run the CLI self-signup flow in references/signup.md to obtain a key without one."
|
||||
required_for: "authenticating the agentmail CLI; not needed before self-signup"
|
||||
optional: true
|
||||
---
|
||||
|
||||
# AgentMail Skill
|
||||
|
||||
AgentMail gives an agent its own email inbox for sending mail, receiving
|
||||
replies, completing email OTP flows, and running inbound email loops. Use it for
|
||||
agent-owned inboxes, not a user's existing IMAP/SMTP mailbox.
|
||||
|
||||
Use the `agentmail` CLI first. Use MCP only when the harness expects MCP tools;
|
||||
use REST only when the CLI is missing a required operation.
|
||||
|
||||
## When to Use
|
||||
|
||||
- The agent needs an email address it owns.
|
||||
- The task involves email OTP flows, replies, threads, labels, or attachments.
|
||||
- The agent needs webhook or WebSocket delivery for inbound mail.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Run commands through the `terminal` tool.
|
||||
- Install the CLI:
|
||||
|
||||
```bash
|
||||
npm install -g agentmail-cli@latest
|
||||
```
|
||||
|
||||
- Export an API key:
|
||||
|
||||
```bash
|
||||
export AGENTMAIL_API_KEY="am_..."
|
||||
```
|
||||
|
||||
No API key yet? Use [signup.md](references/signup.md).
|
||||
|
||||
## How to Run
|
||||
|
||||
Use `--format json` whenever another command or script needs IDs.
|
||||
|
||||
```bash
|
||||
agentmail inboxes list --format json
|
||||
```
|
||||
|
||||
## Quick Reference
|
||||
|
||||
- [AgentMail agent reference](https://agentmail.md): hosted copy.
|
||||
- [AgentMail](https://agentmail.to): product landing page.
|
||||
- [Console](https://console.agentmail.to): API keys and account management.
|
||||
- [Docs](https://docs.agentmail.to): full product documentation.
|
||||
- [signup.md](references/signup.md): self-signup and OTP verification.
|
||||
- [core.md](references/core.md): inboxes, messages, threads, labels, attachments.
|
||||
- [webhooks.md](references/webhooks.md): events to a public HTTPS server.
|
||||
- [websockets.md](references/websockets.md): events to a local agent process.
|
||||
- [mcp.md](references/mcp.md): MCP integration.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Install `agentmail-cli@latest` and verify `agentmail inboxes list --format json`.
|
||||
2. If no API key is available, complete [signup.md](references/signup.md).
|
||||
3. Use [core.md](references/core.md) for inbox, send, read, reply, forward,
|
||||
label, thread, and attachment flows.
|
||||
4. Add [webhooks.md](references/webhooks.md) or
|
||||
[websockets.md](references/websockets.md) only when polling is not enough.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Prefer `AGENTMAIL_API_KEY` over `--api-key`.
|
||||
- Never expose `AGENTMAIL_API_KEY` in prompts, logs, URLs, or committed files.
|
||||
- Use stable `client_id` values for retried create operations.
|
||||
- Prefer `extracted_text` or `extracted_html` for LLM input when present.
|
||||
- React to `message.received`, not messages the agent sent.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
agentmail inboxes list --format json
|
||||
```
|
||||
@@ -0,0 +1,116 @@
|
||||
# AgentMail Core
|
||||
|
||||
Common CLI path: create inboxes, send mail, read incoming mail, reply in
|
||||
threads, label work, and fetch attachments. Need a key first? Use
|
||||
[signup.md](signup.md). Need realtime delivery? Use [webhooks.md](webhooks.md)
|
||||
or [websockets.md](websockets.md).
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
npm install -g agentmail-cli@latest
|
||||
export AGENTMAIL_API_KEY="am_..."
|
||||
agentmail inboxes list --format json
|
||||
```
|
||||
|
||||
## Inboxes
|
||||
|
||||
```bash
|
||||
agentmail inboxes create \
|
||||
--username support \
|
||||
--display-name "Support Agent" \
|
||||
--client-id support-agent-primary \
|
||||
--format json
|
||||
|
||||
agentmail inboxes get --inbox-id support@agentmail.to --format json
|
||||
```
|
||||
|
||||
Omit `domain` to use `@agentmail.to`. Use stable `client_id` values for
|
||||
retried create commands.
|
||||
|
||||
## Send
|
||||
|
||||
```bash
|
||||
agentmail inboxes:messages send \
|
||||
--inbox-id support@agentmail.to \
|
||||
--to customer@example.com \
|
||||
--subject "Hello" \
|
||||
--text "Plain-text body." \
|
||||
--html "<p>Plain-text body.</p>" \
|
||||
--label outreach \
|
||||
--format json
|
||||
```
|
||||
|
||||
Send both `text` and `html` when possible. Recipient limit is 50 total across
|
||||
`to`, `cc`, and `bcc`.
|
||||
|
||||
## Read and Reply
|
||||
|
||||
```bash
|
||||
agentmail inboxes:messages list --inbox-id support@agentmail.to --label unread --format json
|
||||
agentmail inboxes:messages get --inbox-id support@agentmail.to --message-id <message_id> --format json
|
||||
agentmail inboxes:threads get --inbox-id support@agentmail.to --thread-id <thread_id> --format json
|
||||
```
|
||||
|
||||
For LLM input, prefer `extracted_text` or `extracted_html`. Some email has
|
||||
`html` but no `text`.
|
||||
|
||||
```bash
|
||||
agentmail inboxes:messages reply \
|
||||
--inbox-id support@agentmail.to \
|
||||
--message-id <message_id> \
|
||||
--text "Thanks, I will take a look." \
|
||||
--format json
|
||||
|
||||
agentmail inboxes:messages reply-all \
|
||||
--inbox-id support@agentmail.to \
|
||||
--message-id <message_id> \
|
||||
--text "Thanks, everyone." \
|
||||
--format json
|
||||
|
||||
agentmail inboxes:messages forward \
|
||||
--inbox-id support@agentmail.to \
|
||||
--message-id <message_id> \
|
||||
--to teammate@example.com \
|
||||
--format json
|
||||
```
|
||||
|
||||
## Labels
|
||||
|
||||
Use labels as lightweight state: `unread`, `handled`, `needs-review`.
|
||||
|
||||
```bash
|
||||
agentmail inboxes:messages update \
|
||||
--inbox-id support@agentmail.to \
|
||||
--message-id <message_id> \
|
||||
--add-labels handled \
|
||||
--remove-labels unread \
|
||||
--format json
|
||||
```
|
||||
|
||||
## Attachments
|
||||
|
||||
```bash
|
||||
agentmail inboxes:messages get-attachment \
|
||||
--inbox-id support@agentmail.to \
|
||||
--message-id <message_id> \
|
||||
--attachment-id <attachment_id> \
|
||||
--format json
|
||||
```
|
||||
|
||||
Fetch the returned download URL before it expires. Check
|
||||
`agentmail inboxes:messages send --help` for attachment-send flags.
|
||||
|
||||
## REST Notes
|
||||
|
||||
Use REST only when the CLI is unavailable or missing a required operation.
|
||||
|
||||
```bash
|
||||
curl https://api.agentmail.to/v0/inboxes \
|
||||
-H "Authorization: Bearer $AGENTMAIL_API_KEY"
|
||||
```
|
||||
|
||||
Base URLs: `https://api.agentmail.to/v0`, `https://api.agentmail.eu/v0`.
|
||||
|
||||
Error bodies include `name` and `message`; validation errors include `errors`.
|
||||
For `429`, honor `Retry-After` and back off.
|
||||
@@ -0,0 +1,16 @@
|
||||
# AgentMail MCP
|
||||
|
||||
Use MCP only when the user or harness already wants MCP tools. The CLI remains
|
||||
the default path for AgentMail workflows.
|
||||
|
||||
Hosted server:
|
||||
|
||||
```text
|
||||
https://mcp.agentmail.to/mcp
|
||||
```
|
||||
|
||||
Authentication:
|
||||
|
||||
- OAuth in compatible MCP clients.
|
||||
- API key in `?apiKey=...`.
|
||||
- API key in an `x-api-key` header.
|
||||
@@ -0,0 +1,50 @@
|
||||
# AgentMail Self-Signup
|
||||
|
||||
Use this when the agent does not have an AgentMail API key. A human must receive
|
||||
and provide the OTP.
|
||||
|
||||
## Sign Up
|
||||
|
||||
```bash
|
||||
npm install -g agentmail-cli@latest
|
||||
agentmail agent sign-up \
|
||||
--human-email you@example.com \
|
||||
--username my-agent \
|
||||
--source agentmail-cli \
|
||||
--referrer hermes-agent \
|
||||
--format json
|
||||
```
|
||||
|
||||
Export the returned `api_key`:
|
||||
|
||||
```bash
|
||||
export AGENTMAIL_API_KEY="am_..."
|
||||
```
|
||||
|
||||
Verify with the OTP:
|
||||
|
||||
```bash
|
||||
agentmail agent verify --otp-code 123456
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Use a real human email address for `--human-email`.
|
||||
- `human_email` is the signup idempotency key, but signing up again with the
|
||||
same email rotates the API key.
|
||||
- Before verification, the account has one inbox, 10 sends/day, and can only
|
||||
send to the signup human email.
|
||||
|
||||
## First Check
|
||||
|
||||
```bash
|
||||
agentmail inboxes list --format json
|
||||
agentmail inboxes:messages send \
|
||||
--inbox-id my-agent@agentmail.to \
|
||||
--to you@example.com \
|
||||
--subject "AgentMail verified" \
|
||||
--text "My AgentMail inbox is verified." \
|
||||
--format json
|
||||
```
|
||||
|
||||
Continue with [core.md](core.md).
|
||||
@@ -0,0 +1,30 @@
|
||||
# AgentMail Webhooks
|
||||
|
||||
Use webhooks when a public HTTPS server should receive AgentMail events. Use
|
||||
[websockets.md](websockets.md) for local processes without a public URL.
|
||||
|
||||
## Create
|
||||
|
||||
```bash
|
||||
agentmail webhooks create \
|
||||
--url https://your-app.example.com/webhooks/agentmail \
|
||||
--event-type message.received \
|
||||
--inbox-id support@agentmail.to \
|
||||
--client-id support-agentmail-webhook \
|
||||
--format json
|
||||
```
|
||||
|
||||
Store the returned `secret` immediately.
|
||||
|
||||
## Handle
|
||||
|
||||
Headers: `svix-id`, `svix-timestamp`, `svix-signature`.
|
||||
|
||||
1. Verify the raw request body with the webhook secret.
|
||||
2. Dedupe by `svix-id` or `event_id`.
|
||||
3. Return `200` quickly.
|
||||
4. Process asynchronously.
|
||||
5. For `message.received`, load the thread with the CLI and reply if needed.
|
||||
|
||||
Act on `message.received` only. Treating `message.sent` or delivery events as
|
||||
inbound work creates loops.
|
||||
@@ -0,0 +1,55 @@
|
||||
# AgentMail WebSockets
|
||||
|
||||
Use WebSockets when a local agent process needs realtime inbound mail. After an
|
||||
event arrives, use the CLI for inbox, send, reply, label, and attachment work.
|
||||
|
||||
## Python
|
||||
|
||||
The Python example needs the separate AgentMail Python SDK, not the CLI:
|
||||
|
||||
```bash
|
||||
pip install agentmail
|
||||
```
|
||||
|
||||
`AgentMail()` reads `AGENTMAIL_API_KEY` from the environment. If the SDK is
|
||||
unavailable, use the `Raw` WebSocket below instead.
|
||||
|
||||
```python
|
||||
from agentmail import AgentMail, MessageReceivedEvent, Subscribe
|
||||
|
||||
client = AgentMail()
|
||||
|
||||
with client.websockets.connect() as socket:
|
||||
socket.send_subscribe(Subscribe(
|
||||
inbox_ids=["agent@agentmail.to"],
|
||||
event_types=["message.received"],
|
||||
))
|
||||
for event in socket:
|
||||
if isinstance(event, MessageReceivedEvent):
|
||||
print(event.message.subject, event.message.from_)
|
||||
```
|
||||
|
||||
## Raw
|
||||
|
||||
```text
|
||||
wss://ws.agentmail.to/v0?api_key=$AGENTMAIL_API_KEY
|
||||
```
|
||||
|
||||
EU region:
|
||||
|
||||
```text
|
||||
wss://ws.agentmail.eu/v0?api_key=$AGENTMAIL_API_KEY
|
||||
```
|
||||
|
||||
Subscribe frame:
|
||||
|
||||
```json
|
||||
{ "type": "subscribe", "event_types": ["message.received"], "inbox_ids": ["agent@agentmail.to"] }
|
||||
```
|
||||
|
||||
Omit `inbox_ids` and `pod_ids` for the API key scope.
|
||||
|
||||
## Loop Rules
|
||||
|
||||
- Dedupe every event by `event_id`.
|
||||
- Reconnect with backoff and resubscribe after reconnecting.
|
||||
Reference in New Issue
Block a user