# Locus — AgentMail Guide

> **You are on:** `https://beta.paywithlocus.com/` · `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt)
>
> Locus has three environments. Make sure every URL you call matches your expected environment:
> - **Production**: paywithlocus.com (landing) / {api}.paywithlocus.com (API)
> - **Beta**: {beta}.paywithlocus.com (landing) / {beta-api}.paywithlocus.com (API)
> - **Stage**: {stage}.paywithlocus.com (landing) / {stage-api}.paywithlocus.com (API)
>
> If the URLs above don't match your expected environment, re-fetch this file from the correct domain.

Email for AI agents. Create inboxes, send and receive messages, reply, and manage threads — all paid per-request through Locus x402. No AgentMail account or API key needed.

**Base URL:** `https://api.beta.paywithlocus.com/api`
**Auth:** `Authorization: Bearer YOUR_LOCUS_API_KEY`
**Docs:** https://docs.agentmail.to

---

## Endpoints

All endpoints are called via `POST /api/x402/<slug>` with your Locus API key. Payment is deducted from your wallet automatically. All endpoints are subject to [Policy Guardrails](SKILL.md#policy-guardrails). If `PENDING_APPROVAL`, see [Approval Flow](SKILL.md#policy-guardrails).

### POST /api/x402/agentmail-create-inbox — Create Inbox

**Cost:** ~$2.00 USDC

Creates a new email inbox. Returns an inbox ID and email address.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | Yes | Inbox username (becomes `username@agentmail.to`) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/x402/agentmail-create-inbox \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-agent"}'
```

Response:
```json
{
  "success": true,
  "data": {
    "inbox_id": "my-agent@agentmail.to",
    "email": "my-agent@agentmail.to",
    "created_at": "2026-01-15T09:30:00Z"
  }
}
```

**Save the `inbox_id`** — you need it for all other endpoints.

---

### POST /api/x402/agentmail-list-inboxes — List Inboxes

**Cost:** Free

Lists all inboxes owned by your agent.

```bash
curl -X POST https://api.beta.paywithlocus.com/api/x402/agentmail-list-inboxes \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

---

### POST /api/x402/agentmail-send-message — Send Email

**Cost:** ~$0.01 USDC

Sends an email from one of your inboxes. Provide `text` and/or `html` for the body.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Inbox ID to send from |
| `to` | string \| string[] | Yes | Recipient address(es): `"user@example.com"` or `["a@x.com", "b@y.com"]` |
| `cc` | string \| string[] | No | CC address(es) |
| `bcc` | string \| string[] | No | BCC address(es) |
| `subject` | string | Yes | Email subject line |
| `text` | string | Yes* | Plain text body (*text and/or html required) |
| `html` | string | No* | HTML body (*text and/or html required) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/x402/agentmail-send-message \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": "my-agent@agentmail.to",
    "to": ["recipient@example.com"],
    "subject": "Hello from my agent",
    "text": "This email was sent by an AI agent using AgentMail via Locus."
  }'
```

---

### POST /api/x402/agentmail-list-messages — List Messages

**Cost:** ~$0.001 USDC

Lists messages in an inbox.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Inbox ID |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/x402/agentmail-list-messages \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbox_id": "my-agent@agentmail.to"}'
```

---

### POST /api/x402/agentmail-get-message — Get Message

**Cost:** ~$0.001 USDC

Gets full details of a specific message including body and attachments.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Inbox ID |
| `message_id` | string | Yes | Message ID |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/x402/agentmail-get-message \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbox_id": "my-agent@agentmail.to", "message_id": "msg_xyz789"}'
```

---

### POST /api/x402/agentmail-reply — Reply to Message

**Cost:** ~$0.01 USDC

Replies to an email message. Provide `text` and/or `html` for the reply body.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Inbox ID |
| `message_id` | string | Yes | Message ID to reply to |
| `text` | string | Yes* | Plain text reply body (*text and/or html required) |
| `html` | string | No* | HTML reply body (*text and/or html required) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/x402/agentmail-reply \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": "my-agent@agentmail.to",
    "message_id": "msg_xyz789",
    "text": "Thanks for your email! I will look into this."
  }'
```

---

### POST /api/x402/agentmail-list-threads — List Threads

**Cost:** ~$0.001 USDC

Lists email threads in an inbox.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Inbox ID |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/x402/agentmail-list-threads \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbox_id": "my-agent@agentmail.to"}'
```

---

## Common Workflows

### Set Up Agent Email + Send First Message

1. **Create inbox:** `POST /api/x402/agentmail-create-inbox` with `{"username": "my-agent"}` — agent gets `my-agent@agentmail.to`
2. **Send email:** `POST /api/x402/agentmail-send-message` with inbox_id, to, subject, text
3. **Monitor replies:** `POST /api/x402/agentmail-list-messages` with your inbox_id (poll periodically)
4. **Reply:** `POST /api/x402/agentmail-reply` with inbox_id, message_id, text

### Process Incoming Email

1. **List messages** periodically to check for new emails
2. **Get message details** to read full content and attachments
3. **Process with LLM** — classify, extract info, decide action
4. **Reply or forward** based on agent logic

---

## Quick Reference

| Action | Endpoint | Cost |
|--------|----------|------|
| Create inbox | `POST /api/x402/agentmail-create-inbox` | ~$2.00 |
| List inboxes | `POST /api/x402/agentmail-list-inboxes` | Free |
| Send email | `POST /api/x402/agentmail-send-message` | ~$0.01 |
| List messages | `POST /api/x402/agentmail-list-messages` | ~$0.001 |
| Get message | `POST /api/x402/agentmail-get-message` | ~$0.001 |
| Reply | `POST /api/x402/agentmail-reply` | ~$0.01 |
| List threads | `POST /api/x402/agentmail-list-threads` | ~$0.001 |