<<<<<<< HEAD
# Courier — Email Infrastructure for AI Agents

Give your AI agent an email inbox in under 5 seconds.

## What It Does

Courier gives AI agents disposable email addresses that receive real SMTP email — verification codes, magic links, OTPs, password resets — and extracts the codes and links automatically.

## Quick Start

```bash
# 1. Create an inbox (no signup, no auth)
curl -X POST https://getcourier.dev/alias \
  -H "Content-Type: application/json" \
  -d '{"purpose":"test","agent":"demo"}'

# 2. Check for OTP codes and magic links
curl -s https://getcourier.dev/messages | jq '.messages[] | {subject, codes, links}'
```

## API

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `GET /capabilities` | GET | Full API docs |
| `POST /alias` | POST | Create an inbox |
| `GET /aliases` | GET | List inboxes |
| `POST /incoming` | POST | Send email to an inbox |
| `GET /messages` | GET | Get emails with extracted codes |
| `GET /health` | GET | Check service status |
| `POST /x402/invoice` | POST | Lightning payment invoice |
| `GET /llms.txt` | GET | This document |
| `GET /agent.json` | GET | Machine-readable metadata |
| `GET /openapi.json` | GET | OpenAPI 3.0 spec |

## Integrations

- **OpenAI Agents SDK** — `examples/openai-agents-integration.md`
- **Claude Code** — `examples/autonomous-onboarding.sh`
- **Cursor** — `examples/cursor-integration.md`
- **Python** — `pip install requests` then `examples/integration-python.py`
- **Node.js** — `npm install courier-protocol` then `examples/integration-node.js`

## Usage

### Receive OTP codes

```bash
curl -s https://getcourier.dev/messages | jq '.messages[] | select(.codes != []) | {subject, codes}'
```

### Receive magic links

```bash
curl -s https://getcourier.dev/messages | jq '.messages[] | select(.classification.type=="magic_link") | {subject, links}'
```

## Self-Host

```bash
git clone https://github.com/antonioac1/courier.git
cd courier && npm install
```
Single VPS, ~$4/month. Full deployment guide in `docs/`.

## Live Service

https://getcourier.dev — try it now, no setup needed.

**GitHub:** https://github.com/antonioac1/courier  
**npm:** https://www.npmjs.com/package/courier-protocol  
**MCP Registry:** io.github.antonioac1/courier  
=======
# Courier - Email for AI Agents

Give your AI agent an email inbox in under 5 seconds. No signup.
Receive OTP codes, magic links, verification emails, and password resets.

## What It Does

Courier gives AI agents disposable email inboxes that receive real SMTP email.
Automatic extraction of verification codes and magic links.

## Quick Start (5 seconds)

```bash
# Create an inbox - no signup, no auth
curl -X POST https://getcourier.dev/alias \
  -H "Content-Type: application/json" \
  -d '{"purpose":"test"}'

# Check for emails (codes extracted automatically)
curl -s https://getcourier.dev/messages | jq '.messages[] | {subject, codes, links}'
```

## API Endpoints

| Method | Path | What it does |
|--------|------|-------------|
| GET    | /health  | Service status |
| POST   | /alias   | Create an inbox |
| GET    | /aliases | List inboxes |
| POST   | /incoming | Send email to an inbox |
| GET    | /messages | Get emails with extracted codes/links |
| GET    | /capabilities | Full API reference |

## Agent Integrations

### MCP (any agent framework)
```bash
npm install -g courier-mcp
```
Then add to your MCP config:
```json
{
  "mcp_servers": {
    "courier": {
      "command": "courier-mcp"
    }
  }
}
```

### Python (zero deps)
```bash
curl -O https://getcourier.dev/examples/python/courier.py
python3 courier.py create
```

### Node.js (zero deps)
```bash
curl -O https://getcourier.dev/examples/node/courier.mjs
node courier.mjs create
```

### curl / bash
```bash
curl -s https://getcourier.dev/examples/http/quickstart.sh | bash
```

## How Agents Use It

```python
from courier import Courier
c = Courier()

# Create inbox
inbox = c.create_inbox()

# Wait for verification email (polls automatically)
email = c.wait_for_email(timeout=60)

# Extract the code
otp = c.extract_otp()

# Or extract magic link
link = c.extract_magic_link()

# Continue agent execution
```

## Use Cases

- Receive OTP codes for agent signup/2FA
- Receive magic links for auto-login
- Receive password reset links
- Receive verification emails
- Disposable inboxes for AI agents
- Email ingestion for LLM pipelines

## Live Service

https://getcourier.dev - try it now, no setup needed.

## Self-Host

```bash
git clone https://github.com/antonioac1/courier.git
cd courier && npm install
```

**GitHub:** https://github.com/antonioac1/courier
**npm (MCP):** https://www.npmjs.com/package/courier-mcp
**npm (protocol):** https://www.npmjs.com/package/courier-protocol
**MCP Registry:** io.github.antonioac1/courier
>>>>>>> e33696b (v0.2.0: MCP adapter, zero-dependency clients, agent-first positioning)
**License:** MIT
